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Preface 


Documentation Conventions 


The information in this guide is presented in the following way: 
« Square brackets {] indicate options; parenthesis () indicate arguments. 


s Each command and function is addressed separately. The discussion includes a description of the 


command or function’s purpose and operation. This is followed by its syntax and command usage 
format and, finally, by an explanation of the arguments; for example: 


RAYatom(x,y,z,r) 
float Xy,Z,.55 


XYZ 


the coordinates of the centerpoint 


rc the radius 


i 


« Where appropriate, examples and illustrations are included to further clarify the use of a command 
or function. 
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Pixel Machine Features 


The Pixel Machines are graphics generation and display systems that provide high quality image computing. 
The systems are programmable and modular, and are designed to execute complex graphics functions at 
very high speeds. (For a detailed description of the Pixel Machine hardware and software features, refer to 
the Pixel Machines User’s Guide.) 


The Pixel Machine offers a complete set of system commands and a powerful graphics library, PIClib, for 
generating a multitude of images. PIClib’s functions reside on the host computer and provide an interface 
between your application program and the Pixel Machine. Some of the highlights of PIClib include: 


« high-level, 3D object generation (including patches, quadrics, and superquadrics) 
« flat and Gouraud shading 
# texture mapping onto 2D or 3D surfaces 


« multiple light sources of different types 


antialiasing by supersampling for photorealistic 3D rendering 

# 32-bit floating point z-buffer for highly accurate depth precision 
# 32-bit double buffering 

= a robust set of interactive 3D graphics functions 


* a unique set of rgbz buffer copy routines 


[n addition to the graphics library, PIClib, a ray tracing library, RAY|ib, is available for the Pixel Machine. 
RAYIib is composed of a powerful set of tools for generating high-quality graphics images and includes 
primitives for generating and manipulating 3D computer models and describing their physical attributes. It 
can be used as a high-end renderer to create realistic images for use in 3D visualization, industrial design, 
and television/ motion picture production. 


RAYIib includes many sophisticated features that enable you to achieve superb visual realism while main- 
taining the high rendering speed made possible by the paraile! architecture of the Pixel Machine. These 
features include: 


« Realism - RAYIib generates the shadows, reflections, and transparency that make a computer- 
generated image more realistic. The user can control the reflective and specular components of an 
object as well as the object’s degree of transparency. All of these features (shadows, reflections, and 
transparency) can be disabled in the user’s program for a quick preview of the scene before render- 
ing the final image. 


e Light Sources - Multiple light sources of any color can be used to produce a variety of lighting 
effects. The types of light sources available are point, direct (infinite), and area. Direct light sources 
produce lighting that ts sumilar to sunlight. Area light sources have the effect of producing soft, 
natural shadows. 


« Texture Mapping - Any 2D texture can be mapped onto objects created by RAYlib. These textures 
can be used to generate realistic surfaces, such as wood grains, clouds, marble, etc. The texture 
maps can have surface properties, such as reflectance and transparency, on a pixel by pixel basis. As 
many as 64 texture maps can be used at one time. Texture maps can be as large as 4K x 4K. 


Antialiasing - Adaptive stochastic antialiasing can be turned on to eliminate rough, jagged edges. 
The user can control the minimum and magmum number of samples and the contrast threshold. 


1-2 RAYlib User's Guide, Version 0.5 


Pixel Machine Features 





« Double Buffering - Double buffering can be used to create smooth animations. When double 
buffering is enabled, objects are rendered into the off-screen buffer. This buffer is swapped with the 
on-screen buffer when instructed to do so by the user. 


All application programs for the Pixel Machine are written in C. As a result, life-like images can be created 
quickly and easily without the need for machine-specific knowledge. For more information on the C pro- 
gramming language, refer to The C Programming Language by Brian W. Kernighan and Dennis M. Ritchie 
(1978, Prentice-Hall, Inc., Englewood Cliffs, New Jersey, or the updated 1988 edition). 


The sections that follow provide an overview of RAYlib’s functions and a brief discussion of the differences 
between PIClib and RAYIib. 
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RAYlib Functions 


RAYlib functions are grouped into the following categories: 





Category Functions in this category are used to... 
er 
Control initialize the machine, start ray tracing, and terminate a ray trace 
session. 
Graphics primitives generate three dimensional polygons and atoms, render superqua- 


drics (spheres, cylinders, ellipsoids, toroids, and hyperboloids of one 
and two sheets) and generate patches. Surface properties for these 
three dimensional objects are supported. 


Bounding volumes initialize, terminate, and record three dimensional extents of objects. 
Proper use can greatly enhance the ray tracing execution speed. 









perform a wide variety of operations such as controlling the transla- 









Transformations 
tion, scale and rotation of objects. Viewing and projection are also 
included in this category. 

Shading and Lighting control the position, orientation, and intensity of light sources. 
Ambient light and light switch control are handled in this category. 
Surface properties for objects as well as shading modes are defined 
using these functions. 

Viewports create and manipulate viewports. 

Antialiasing eliminate jagged edges in the objects of a scene through the use of 
stochastic sampling. 

Video enable and disable the video map from the shadow map, load and 





retrieve color rgb maps as well as alpha overlay color maps. 
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Differences Between RAYlib and PIClib 


The internal operation of RAYIib is fundamentally different from PiClib. While PiClib renders each 
geometric primitive as it is received by the Pixel Machine, RAYlib maintains a database of all geometry 
being rendered. Consequently, when using RAYI1ib you must define ail objects and viewing parameters 
prior to rendering. If a change is necessary in a scene, the entire image must be redefined and a complete 
ray trace invoked again. Although slower than P!Clib, RAYIib provides the realism often required for high 


quality output. 


Despite the internal differences, P!Clib users will find that their programs are easily ported to RAYIib 
because P{Clib and RAYlib share a common syntax, common functionality (although not every RAYIib func- 
tion has a corresponding PIClib function and vice versa) and a common set of structure definitions 


(typedefs). 


There are, of course, some differences, and the remainder of this section is devoted to helping the PIClib 
user quickly become a RAYlib user. To this end, the first subsection, “Differences in Common Structure 
Definitions’, briefly describes differences in the way elements of some common structure definitions are 
used by each library. The second subsection, "Differences in Common Functions’, discusses the ways in 
which some RAYlib functions differ from their PiClib counterparts. The final subsection, "Functions 
Unique to RAYtib" provides an overview of the RAYIlib functions that do not have a PIClib counterpart. For 
a detailed description of each RAYIib function, refer to Chapter 3 of this guide. 


Differences in Common Structure Definitions 


The folowing structure definitions are accessed differently by each library. 


Structure 


RAYsurface_model 


RAYlight source 





Usage 





The RAYsuriace_model structure contains the same elements as the 
PiCsurface_ model structure, but these elements are used slightly 
differently. In RAYIib, the a_* ands * color components are 
ignored, and the speculanty, reflectivity, and refraction_index elements 
are used. The reverse is true in PICtib. 


The RAYlib structure RAYlight source has a structure element, 
intensity, that applies to all RAYtib light sources. Additionally, the 
fields samples, vertices, and vertex have been added to support arca 
light sources. 





Differences in Common Functions 


The following RAYIib functions are applied differently than their PiClib counterparts: 
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RAYput_surface_model() 





RAYatom() 


RAYshade_mode() 





Functions Unique to RAYlib 








Usage 


In RAYIib a call to RAYput_surface_model() actually allocates 
memory for a new surface model. To reuse a surface model, 
RAYset_surface_modei() should be called with the value that the 
function call to RAYput_surface_model() returned. Note that only 
RAYput_surface_model() returns a meaningful value. The 
corresponding PIClib function does not. 


The radius of the atom primitive defined by RAYatom() is scaled by 
the average scale factor determined by the current transform. In 
P\Clib, no modeling transformations are applied to the radius of an 
atom, even though the projection transform is applied. 





The RAYshade_mode() function is used in RAYI1b to control shading 
effects such as shadows, reflections, and antialiasing. 


The following functions exist only in RAYIib: 


RAYtrace() 


RAYopen_bounding volumeQ 


RAYclose bounding volume() 
RAYambient_inteasity() 





RAYbackground color() 





1-4 RAYlib User's Guide, Version 0.5 


Functioa Description 


Begins the ray tracing process. Nothing is rendered until RAY- 


trace() is called. 





RAYstatistics() Enables/disables the printing of ray tracing statistics. 


Begins the computing of bounding volumes. Proper use of bounding 
volumes improves RAYIib’s performance. 






Ends the computing of bounding volumes. 


Sets the intensity of the ambient light. 





Sets the color of a primary ray when it does not intersect any object 
in a 3D scene. 





RAYclear_viewport() 
RAYsam ples () 


RAYput _texture() 
RAYset_texture() 


RAYset_surface_modei() 





Differences Between RAYIib and PiClib 


Descriptioa 


Clears the current viewport to a specified color. This function is pri- 


marily used to clear the entire screen or to display drop shadows. 
Because RAYIib will set every pixel! in the current viewport when it 
ray traces, there is no need to clear the viewport being ray traced. 


Defines the minimum and maximum oumber of samples to take 
within a pixel when antialiasing is being done. It also defines the 
contrast threshold to be used to determine if the maximum amount 
of antialiasing is needed. 


Allocates regions of resident texture memory or host memory for 
virtual textures. 


Sets the current texture map to the specified texture id; the texture 
id should be the value returned by RAYput_texture. 


Sets the current surface model to the specified surface id; the id 
should be the value returned by the RAYput_surface_model call. 
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Getting Started 


Before you can compile and run your programs, you need to make sure that the hardware is initialized and 
the software environment is set up correctly. When you first turn on the Pixel Machine, you must initialize 
the hardware to a known state. This is accomplished by executing the hypinit command. Once the 
hardware is initialized, you must boot the Pixel Machine by executing the rayboot command before you can 
run RAYlib graphics programs. For more information about hypinit and rayboot, refer to Chapter 2 of this 
guide. 


The software environment must be set up at installation time and after any changes to the system’s 
configurations (for example, upgrading the Pixel Machine or changing the Transformation Pipeline 
configuration). The procedures for setting up the software environment are described below. 


Defining the Software Environment 


Before using the Pixel! Machine, the proper environment must be created. The /usr/hyper directory con- 
tains files for defining the Pixel Machine environment. For csh users, a login (.hyper_login) and a -cshre 
(.hyper_cshrc) are provided in /usr/hyper. ksh users will find a .profile (.hyper_profile) and a env 
(.hyper_env) residing there as well. 


-hyper_login and -hyper_profile define Pixel Machine-specific environment variables and update some 
standard UNIX system environment variables in order to provide easy access to Pixel Machine software 
and manual pages. -hyper_cshre and -hyper_env establish aliases (or shortcuts) for redefining environment 
variables and performing system initialization functions. 


If you are using csh, you should source .hyper_login and -hyper_cshrc into your login and -cshre files, 
respectively. To do so, edit your Jogin file, and add the following to the end of the file: 


source /usr/hyper/.hyper_login 
Then edit your .cshre file and add the following to the end of the file: 
source /usr/hyper/.hyper_cshrc 


If you are using ksh, you should . (dot) .hyper_profile and .hyper_env into your .profile and .env files, 
respectively. To do so, edit your .profile and add the following to the end of the file: 


/usr/hyper/.hyper_profile 


Then edit your -env file and add the following to the end of the file: 


/usr/hyper/.hyper_env 


It is important to note that the files provided in /usr/hyper are generic, and the environment variables 
defined in these files may not initially correspond to your specific machine configuration. Before using the 
files provided, your system administrator should make any necessary modifications to ensure that the Pixcl 
Machine environment variables are defined appropriately for your machine. A descripuon of cach environ- 
ment variable and a list of its possible values is given below. 
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The HYPER MODEL variable specifies the Pixel Machine model and Transformation Pipeline 
configuration. The table below describes the values that should be assigned to this variable, depending on 
what modc. and configuration you have. 


m2 Pi ie ile ie | 
rad___| ited dual pe, TIE 
oe 























Pixel Machine 940, single Pipe, 1280x1024 


ee oe 
eee 
[4d Pixel Machine 964, dual Pipe, 1024x1024 
Pixel Machine 964, dual Pipe, 1280x1024 


A lower case "n” appended to the model number denotes an NTSC model whose resolution is 720x486. 
/NOTE| A lower case “p” appended to the mode! number denotes a PAL mode whose resolution is 720x576. 


3 





————— 


The HYPER PATH variable specifies the full pathname to the host directory that contains the Pixel 
Machine software (for example, /usr/hyper) 


The HYPER PIPE variable specifies the Pipeline configuration (serial or parallel) for systems with two 
Transformation Pipelines. 


The HYPER_UNIT variable specifies the Pixel Machine unit number. Up to four machines (numbered 0), |, 
2, 3) can be connected to a host computer. 
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Writing RAYlib Programs 

At the beginning of each application C program you write, you need to include the RAYlib header file. This 

file includes type definitions, constants, and external definitions, and is included by the following statement: 
#include = “raylib.h" 


The first RAYIib function called within an application program should be RAYinit. This function initializes 
the viewport to a full screen (either 1024x1024, 1280x1024, 720x480 or 720x576 depending on your Pixel 
Machine configuration) and sets default precisions. RAYInit returns a value of RAY _ERR_OK if the initial- 
ization is successful, or a value of RAY _ERR_ARG if it failed. For a complete description of RAYinit, see 
that manual page in the RAYlib Reference Manual. 


The last RAYIib function called within an application program is usually RAYexit. It performs various clean 
up functions, and unlocks the Pixel Machine making it accessible to other users. Be sure to include it at the 
end of your program. 


Compiling RAYlib Programs 


To compile your RAYIIb program, link raylib.a and the math library as follows: 
ce -ISHYPER_PATH/include file.c SHYPER_PATH/lib/raylib.a 4m -0 file.exe 


where, file.c is the name of the file containing the program. You can also link with raylib_ffpa.a to run on a 
Sun with a floating point accelerator board. 


The system will compile your program and create an executable file called file.exe (if the -o flag is omitted, 
the executable file will be called a.out). To run the program, type the name of this executable file. 
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Commands and Utilities 


Pixel Machine System Commands and Utilities Bu 
hypenv 2-1 
hypfree 2-2 
hypid 2-2 
bypinit 2-3 
hyplock 2-5 
hypstat 2-6 
rayboot 2-7 


Commands and Ltilities 





Pixel Machine System Commands and Utilities 


The system commands and utilities allow you to perform utility and administrative functions, such as initial- 


izing the hardware, loading the RAYIlib processor programs into the Transformation Pipeline(s) and Pixel 


Nodes, or simply locking your Pixel Machine. 


The system commands described in this section are: 






Tenis | Reewesabetedea 
font | Bisisnete dew 
Tpit‘ ns heaters 
Tania [token 













The system utilities described in this section are: 


hypenv 


The hypenv command displays the current values of the Pixel Machine environment variables. The 






Loads RAYlib software into the Pixel Machine. 





environment variables must be set on the host workstation either in a login procedure or on the command 
line before using the Pixel Machine. (See Chapter 1 of this guide for procedures for setting Pixel Machine 


environment variables.) [f no options are specified, the status of all environment variables are displayed. 


Command usage is: 


hypenv [-D] {-M] [-P}(-U] (-u] 


The options are as follows: 
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-D Print current value of HYPER_PIPE (serial or parallel) 

-M Print current value of HYPER_MODEL environment variable 
-P Print current value of HYPER_PATH environment variable 
-U__sPrint current value of HYPER_UNIT environment variable 


-u Print command usage format 


If you enter hypeny, the system displays the following typical response: 


Model: 964d Pipe: parallel Unit: 0 Path: /usr/hyper 


hypfree 


The hypfree command releases one or more Pixel Machines that were locked with the hyplock command. 
If no options are specified, the command releases only the current unit. 


Command usage: 
hypfree (-a] (-u] 
The options are as follows: 


-a Free all units 


‘uu Print command usage format 


hypid 
The hypid command generates a list of ID data on the Nodes in the Pixel Machine. 


Command usage: 
hypid [-a] [-d node} [-g node] {-w] [-u] 


The options are as follows: 
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-a Print ID data on all Nodes 

-dnode Print ID data of Pixel Node number node or ail 

-giode —_— Print [D data of Transformation Node number node or ail 
-w Write the ID data into the selected Node. 


“u Print command usage format 


If you enter hypid -d1, the system displays the following typical response for a Pixel Machine 964 model 
booted with PIClib: 


FS ea eG 


/ 
| 


Drawing node 1 identification data: 


node id: 1 
x nodes: 8 . | 
y nodes: 8 

x offset: 0 

y offset: 1 

program: 'pic964.dsp' 

semaphore: 0 } 


: Z 
y 
a 


The ID data provides the following information: 


« node id contains the sequential numbering of the Transformation and Pixel Nodes. The Pixel Nodes 


range from 0 ton (n = 63 on a model 964). The Transformation Nodes range from 9 to 8 for a sin- 
gle Pipe configuration; from 0 to 17 for a dual Pipe configuration. 


« x nodes and y nodes indicate the configuration of the buffer in an N x M array. 


« x offset and y offset indicate the position of the processor tn the 2D array. 


program lists the name of the DSP executable program that is loaded into memory. 


semaphore contains system information. 


hypinit 


Each ume you power up the system, you necd to initialize it to a known state. The hypinit command ini- 
tializes the Pixel Machine to its default state. If no options are specified, hypinit initializes the Transtorma- 
tion Nodes and FIFOs, the Pixel Nodes, the drawing mode register, the Transformation Pipeline, and the 


video. 
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You can also use this command to reinitialize the Pixel Machine whenever you want the system to return to 
its initial state. 


Command usage is: 


hypinit (-b] {-d] [-g] [-m] (-p] (-q] [-Q] [-r] (-v] (-V] [-u] 


The following options may be used to limit initialization: 


-b Initialize the VME bus repeater 
-d Initialize the Pixel Nodes 
a4 Initialize the Transformation Nodes 


-m [Initialize the drawing mode register to the current configuration model, disable over- 
lay video, and turn off testing mode. 


-p Reconfigure Pipelines in series or parallel based on the environment variable 
-q enables pipelined writes 

-Q disables pipelined writes 

-r Reset input and output Pipeline FIFOs 

“v Initialize video registers and lookup table 

-V___— Do not initialize video 


-u-—s- Print command usage format 


[f you enter hypinit, the system displays the following typical response. 
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System contiguration: 

' geometry cards: 2 nodes: 18 

geometry pipes: muitiple in parallel 

i drawing cards: 16 nodes: 64 

drawing node dram: 256 {kbytes} vram: 256 [kbytes] 
drawing pixel interieaving x: 8 y: 8 t 
drawing node/screen scale x: 0.125 y: 0.125 | 
video format: high resolution 

! video screen size x: 1024 y: 1024 


VMEbus-repeater csr register: active { no_pipeline lights: 0 no_reset cool_temperature }. 
Geometry nodes(0-17]: active [ halted pir16 eni dma auto pdf }. 

Drawing nodes({0-63]: active [ haited pir16 eni dma auto ] errors [ sync }. 

Geometry output (write ) fifo{0] flags: active { empty ]. 

| Geometry input (feedback) fifo(0] flags: active [ ernpty J. 

| Geometry output (write ) fifo(1] flags: active [ empty ]. 

Geometry input (feedback) fifo(1] flags: active ( empty J. 


Oraw mode registers [0-15]: active. 








Video car register: active [ type: 964 shadow no refresh no_ shift yo: 
i 964X no_psyncd no_psync! hsize: 1280 j. 


Pe oe os ee ae ee ee I 


hyplock 


The hyplock command locks the current Pixel Machine and prevents other users who are timesharing the 
system from accessing it. (The Pixel Machine is not multitasking.) Before you log off, remember to unlock 
the system by executing the hypfree command. 

Command usage: 


hyplock {-u] 


The options are as follows: 


-u-—- Print command usage format 
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hypstat 
The hypstat command displays the system status of the Pixel Machine. 
Command usage is: 

hypstat [-u] 


The options are as follows: 
-u——- Print command usage format 


If you enter bypstat, the system displays the following typical response. If you get an error message, enter 
the hypinit command first and then hypstat: 


/ a 
| System configuration: 
geometry cards: 2 nodes: 18 
| geometry pipes: muitipie in parallel 
drawing cards: 16 nodes: 64 
drawing node dram: 256 (kbytes] vram: 256 [kbytes] 
drawing pixel interleaving x: 8 y: 8 
drawing node/screen scale x: 0.125 y: 0.125 
video format: high resolution 
video screen size x: 1024 y: 1024 


VMEbus-repeater csr register: active ( NO _pipeline lights: 0 no_reset cool temperature J. i 


; Geometry nodes(0-7]: active { halted pir16 eni dma auto pdf }. 
Geometry node{8]: active [ halted pir16 eni dma auto J. 
Geometry nodes{9-16]: active [ halted pir16 eni dma auto pdf }. ! 
Geometry node(17]: active { halted pir16 eni dma auto J. 


Geometry output (write ) fifo(0] flags: active { empty J. 
Geometry input (feedback) fifo(0] flags: active ( empty J. 
Geometry output (write ) fifo(1] flags: active [ empty J. 
Geometry input (feedback) fifo(1] flags: active [ empty J. 


Drawing nodes (0-63}: active [ halted pir16 eni dma auto } errors [ sync }. 


Draw mode registers{0-15]: active. 


Video csr register: active [ type: 964 shadow no_retresh no shift yo: : 
964X no _psyncO no_psynct hsize: 1280 J. 
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rayboot 


rayboot initializes the machine (with the exception of the video) and loads the Transformation and Pixel 
Nodes with the appropriate software for the machine based on the value of the HYPER MODEL and 
HYPER _PIPE variables. The software that is downloaded to the Transformation and Pixel Nodes resides 
in the directory specified by HYPER_PATH. To initialize the Pixel Machine video, use the hypinit com- 
mand discussed earlier in this chapter. 


rayboot should be executed: 
» when the machine is powered up 
« after changing any of the environment variables, HYPER_MODEL, HYPER_PATH, HYPER PIPE 
and HYPER_UNIT 
« after running PIClib demos 
« after using DEVtools 
» in the event of RAYIib software failure 


It is important to note that after changing the HYPER_MODEL environment variable, you must first initial- 
ize the Pixel Machine by executing hypinit -v in order to initialize the video registers and lookup tables. The 
rayboot command can then be executed to download the appropriate software to the Transformation and 
Pixel Nodes. Because the video registers and lookup tables are re-initialized by the first call to hypinit, you 
need to re-execute picrt and picgamma if you are using these utilities. 


| For more information about piert and picgamma, refer to Chapter 2 of the PI[Clib User’s Guide. 
' NOTE 
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Control Functions 3-1 
RA YinitO 31 
RA Yexit() 3-2 
RA YtraceQ) 3-2 
RA Ystatistics() 3-3 
RA Yext_immediate() 3-4 
RA Yhalt() 3-5 
Graphics Primitives - Polygons and Atoms a7 
RAYpoly_close() 3-7 
RAYpoly_point_3d() 3-8 
RAY_poly_point_av() 3-8 
RAY_poly_point_uv() 3-8 
RAY_poly_point_ov_uv() 3-9 
RA Yatom() 3-10 
Graphics Primitives - Quadrics and Superquadrics 311 
RA Yquadric_precision() 3-11 
RA Ysphere() 3-12 
RAYsuperq_ ellipsoid() 3-12 
RAYsuperq_torus() 3-14 
RAYsuperq_ hyper 1() 3-15 
RAYsuperq_hyper2() 3-16 
Graphics Primitives - Patches Snii7 
Generating Patches 3-17 

« Bexier Patches 3-18 

» Hermite Patch 3-18 

« B-Spline Patch 3-19 

« Sixteen-Point Form Patch 3-19 
RAYpatch geometry _3d() 3-19 
RAY patch _precision() 3-20 
RAY put _basis() 3-20 
RAYselect_patch_basis() 3-21 
Bounding Volumes 324 





RAYopen_ bounding volume() 3-24 





RAYclose_bounding volume() 3-25 
Transformations 3-26 
Transformation Matrices 3-26 
Transformations - Projection Functions 3-29 
RAYpersp_project() 3-29 
RA Ywindow_project() 3-30 
Transtormations - Viewing Functions 3-31 
RA Ylookat_view() 331 
RA Ylookup_view() 3-32 
RAYcamera_view() 3-32 
RAY polar_view() 334 
Transtormations - Modeling Functions 3-35 
Rotation 3-36 

« RAYrotate Functions 3-37 

« RAYrotate_vector() 3-38 

« RAYput_rotate_d Functions 3-39 

« RAYrotate_d Functions 3-40 
Translation 3-40 

« RAYtranslate Functions 3-40 

+ RAYput_translate_d Functions 341 

« RAYtransiate_d Functions 344 
Scaling 3-42 

e RAYscale Functions 3-42 

« RAYput_scale_d Functions 343 

« RAYscale_d Functions 343 
Transtormations - Control Functions 3-45 
Modeling and Viewing Transformation Control 3-45 
RAYget_inverse_transform() 3-45 
RAYget_normal transform() 3-46 
RAYget_transform() ; 3-46 
RAYpremultiply_transform() 3-46 
RAY postmultiply_transform() 3-47 
RAY push_transform() 3-47 
RAY pop_transform() 3-47 
RAYput_transform() 3-48 
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RAYput_identity_transform() 


Viewports 
RAY get_screen_size() 
RAYput_viewport() 


Shading and Lighting 
RAYambient_intensity() 
RA Ylight_ambient() 

RA Ybackground _color() 
RAYput_light_source() 
RA Ylight_ switch() 
RAYput_surface_model() 
RAYset_surface_model() 
RAYput_texture() 
RAYset_texture() 
RAYshade_mode() 


Antialiasing 
RA Ysamples() 


Display Control - 
RAYclear_viewport() 
RA Ydouble_buffer() 
RAYswap_buffer() 

RAY get_buffer_mode() 
RAYget_buffer() 

RAY put scan line() 
RAYget_scan line() 

RA Ybroadcast_data() 
RAYcopy_front_to_back() 
RAYcopy_back to_ext() 
RAYcopy_ext_to_back() 








Video Functions 

RA Yupdate_map() 
RAYput_color_map() 
RAYput_color_map_entry() 
RAYput_alpha_map{) 
RAYput alpha map _entry() 
RAYget_color_map() 
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Control Functions 


The RAY1ib system control functions perform basic setup and “housekeeping” operations to allow applica- 
tions to communicate with the Pixel Machine. Prior to using these programs, the Pixel Machine ray tracing 
software must be loaded into the Pixe! Machine hardware (see Chapter 2 of this guide). These control 
functions are: 


« RAYinitO 

a RAYexit() 

= RAYtrace() 

a RAYstatistics() 

a RAYexit_immediate() 
« RAYhait() 


RAYinit() 


int RAYinit() 


RAYinit is always the first function called in every RAYIib program, and should be invoked only once. It 
initializes the viewport to full screen (1024x1024 or 1280x1024 for high resolution models, 720x480 for 
NTSC models and 720x576 for PAL), initializes the transformation matrix to the identity matrix, and sets 
various system parameters to their default values. RAYinit also sets up a signal handler to catch the follow- 
ing signals: 

« hangup 

= interrupt 


« software termination 
When the signal handler is invoked, it calls RAYexit_immediate and terminates ray tracing on the Pixel 


Machine. RAYinit will not override previously established signal handlers. If the user has established a sig- 
nal handler for any of the above signals prior to calling RAYinit, that signal handler will remain in cffect. 


RAYinit returns an integer value of RAY_ERR_OK if the initialization succeeds and RAY_ERR_OPEN if it 
fails. 
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RAYexitQ 





int RAYexit() 





RAYexit is usually the last RAYIib function called in a program. It halts all transformation and drawing node 
processors in the Pixel Machine hardware and closes the device. Signal handlers established during RAYinit 
are reset to their default actions. 


| RAYexit should not be used in a signal handler; instead use RAYexit_immediate. 
, NOTE 
| 





RAYtraceQ) 





int RAYtrace() 





RAYtrace initiates ray tracing in the Pixel Machine. Calls to RAYlib prior to RAYtrace define the objects, 
viewing, light sources, and other aspects of a scene. When RAYtrace is invoked, the data that has been col- 
lected is rendered into the frame buffer. RAYtrace does not return until the entire ray tracing process is 
completed. The RAY1ib database is then re-initialized to accommodate animation sequences. 


Unlike PIClib which renders objects as they are defined, RAYIib renders nothing until RAYtrace is called. 
NOTE! Refer to the section, “Differences between RAYlib and P!Clib” in Chapter 1 for more information. 





RAYtrace returns an integer value indicating the completion status of the ray tracer. The possible return 
codes are: 


Crear eo 
match the aumber of bounding volume closes 
















| 



















RAY_HALTED 





RAY _ERR_INTERNAL 
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Example: 


eee ee a 


f 

/ 

[  #inciude “raytib.h* \ 
| maing 

| { 

| it (RAYinit) != RAY_ERR_OK) exit(1); 


RAYtrace(); 
i RAY exit); 








RAYstatistics() 


void RAYstatistics(mode) 
int mode; 


mode = statistics to be printed at the end of the ray tracing 
run. 


RAYstatistics determines what ray tracing statistics, if any, will be printed at the end of a ray tracing run. 
This function is called with an argument, mode, which can be set to any one or combination of values 
described in the table below. Modes are combined by adding them together. The default mode is 

RAY_ TIMINGS + RAY STATISTICS. 


“RAY_OFF no statistics 

RAY STATISTICS total pages and object counts 
RAY TIMINGS liming statistics 

RAY PAGE STATISTICS | page and page fault statistics 








RAY ALL STATISTICS print all of the above staustics 
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RAYexit_immediate() 
void RAYexit_immediate() 


RAYexit_immediate replaces RAYexit for signal handlers. If an application signal handler is going to ext 
immediately, it should call RAYexit_immediate to halt the pixel nodes and clean up the system. If the pixel 
nodes have begun ray tracing, they will continue to do so even after the program exits, unless a 
RAYexit_immediate is called. 


RAYexit should still be used for normal program exts. 
| NOTE 
ee 


Example: 
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'  /* example of a signal handler that exits immediatety */ 








i #include <signal.h> 
#include  ‘rayiib.n* 
{ 
void 
mysignal(sig,code,scp) 
int sig, code: i 
struct sigcontext “scp; 
{ 
/* in the event of an interrupt, this signal handler will 
terminate ray tracing and eat immediatety */ ! 
| RAYexit_immediate(); 
exnt(); ! 
} 
main() 
{ ‘ 
int return value; 
signal(SIGINT, mysignai); | 
| it ( RAYinit() != RAY_ERR_OK) exit(1); 
! 
return_value = RAYtrace(); 
! RAYexit(); 
{ } 
RAYhalt() 


void RAYhalt() 


RAYhalt is used to post a request to halt the ray tracer. Typically, it is called from a signal handler in 
response (0 a user request. The halt request is only recognized by the routine RAYtrace. [fa halt request 
is encountered at any ime during the execution of a call to RAYtrace, ray tracing is terminated and RAY- 
trace returns RAY HALTED. Execution may then continue in the application program as though RAYtrace 
had completed normally. 
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If RAYhalt is called from a signal handler, it is important that the signal handler return to continue execu- 
tion, or else the halt request will never be seen and the Pixel Machine may continue ray tracing. [f a signal 
handler must exit, RAYexit_{mmediate should be called to halt the Pixe! Machine. 


Example: 








| /* example of a signal handler that requests a halt */ 
i 
| #include <signal.h> 
| #include  “raylib.h" 
void 
mysignal(sig,code,scp) 
int Sig, code: 
struct sigcontext "scp; 
i { 
' /* in the event of an interrupt, this signal handler will 
' post a request to terminate ray tracing and then return */ 
‘ RAYhai(); 
i oF 
maing 
bd 
| int return value; 
| signal(SIGINT, mysignal): 
t 
| if ( RAYinit) != RAY_ERR_OK) exit(1); 
! 
return_vaiue = RAYtrace(); 
| ft (return_value == RAY HALTED) 1 
| printt(Ray tracing halted because of user interrupto); 
i 
| RAYexit(; 
| } 
\ 
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Graphic primitives allow an application to draw three dimensional polygons and surfaces. The specific 
topology is defined in this section. Surface characteristics are covered in the “Shading and Lighting” sec- 
tion. All surfaces are rendered using the current surface model, which is established by a call to 
RAYput_ surface_model or RAYset_surface_model. 


Polygons may be texture mapped and/or have normal vectors defined at the vertices. Associated functions 
are: 


« RAYpoly close() 
« RAYpoly point 3d(x,y,z) 
a RAYpoly point ov(x,y,z,nx,ny,n2) 
= RAYpoly point _uv(x,y,z,u,v) 
] RAYpoly_ point_ov_uv(x,y,z,0x,ny,nz,u,v) 
« RAYatom(x,y,z,r) 
eau When using the RAYpoly point functions, note that all polygons must be convex and should be planar 


at 
t 


RAYpoly close() 
void RAYpoly_ close() 


This function closes a polygon by connecting the last polygon point to the first vertex. The polygon is ren- 
dered using the current surface model. This function must be used after a series of polygon defining calls 
such as: 


« RAYpoly point 3d 
# RAYpoly point ov 
a RAYpoly point uv 
= RAYpoly point _av_uv 
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RAYpoly point_3dQ 





void RAYpoly_point_3d(x,y,z) 
float x,y,z; 


XYZ = the xy and z coordinates of a vertex 





RAYpoly_point_3d is used in sequence to define a series of 3D vertices that com pose a polygon. The 
sequence of coordinates defined by each call to a RAYpoly point 3d function is not connected until a 
RAYpoly_close function is specified. The polygon is drawn using the current surface model. 


RAY_poly point_nvQ 





void RAYpoly_point_nv(x,y,z,nx,ny,nz) 
float x,y,z,nx,ny,n2z; 


the xy and z coordinates of a vertex 


XYZ 


nx,oy,0zZ = normal vector at the vertex 





RAYpoly_point_av is used in sequence to define a series of 3D vertices that compose a polygon with nor- 
mals at each vertex. The sequence of coordinates defined by each call to a RAYpoly_point_av function is 
not connected until RAYpoly_ close is specified. The polygon is drawn using the current surface model. 


A surface normal is specified at each vertex. The normal vector points outward in a closed solid object. 


RAY _poly_point_uv(Q) 





void RAYpoly point _uv(x,y,z,u,v) 
float x,y,Z,U,V; 


i 


XYZ the xy and z coordinates of a vertex 


u,v = texture indices at the vertex 
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RAYpoly_point_uv is used in sequence to define a series of 3D vertices that compose a polygon with tex- 
ture indices at each vertex. The sequence of coordinates defined by each call toa RAYpoly_point_uv func- 
tion is not connected until RAYpoly_close is specified. The polygon is drawn using the current surface 
model. 


The texture indices are specified at each vertex. These indices must be non-negative floating point values. 
The edges of the texture are defined to be from 0.0 to 1.0, regardless of the size or aspect ratio of the tex- 
ture. Indices greater than 1.0 cause the texture to wrap. 


| Texture indicies are currently limited to the range 0.0 to 16.0. 
‘ NOTE| 
ove 


This function is unique to RAYIib and has no equivalent in PiClib. 


RAY_poly point_nv_uvQ 





void RAYpoly point ov_uv(x,y,z,0x,ny,02,u,v) 
float Xy2,nx,ny,02,u,Y; 


XYZ = the xy and z coordinates of a vertex 
mx.nynzZ = normal vector at the vertex 
uv = texture indices at the vertex 


RAYpoly_point_av_uv is used in sequence to define a series of 3D vertices that compose a polygon with 
normals and texture indices at each vertex. The sequence of coordinates defined by each call to 
RAYpoly_point_av_uv is not connected until RAYpoly close is specified. The polygon is drawn using the 
current surface modeL 


The texture indices are specified at each vertex. These indices must be non-negative floating point values. 
The edges of the texture are defined to be from 0.0 to 1.0, regardless of the size or aspect ratio of the tex- 
ture. Indices greater than 1.0 cause the texture to wrap. 


| Texture indicies are currently limited to the range 0.0 to 16.0. 


| NOTE! 
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RAYatom() 





void RAYatom(x,y,z,r) 


float x,y,z,05 
XYZ = center of the atom 
r = radius 


RAYatom draws a spherical atom centered at a given location with a specified radius. The atom’s center 
and radius are transformed by the current transformation matrix. The radius of the atom is scaled by the 
average scale factor determined by the current transform. Thus, if the modeling transform has explicit dis- 
tortion, the atom will still be round when rendered. The atom is rendered using the current surface mode}. 


Whenever possible, RAYatom should be used in place of RAYsphere. RAYatom is faster and more accu- 
rate than RAYsphere because RAYatom is rendered as a single primitive, while RAYsphere (and all the 
other superquadrics and patches) are tessellated into polygons. RAYsphere should only be used when 
independent scaling is required along each axis of the sphere. 





; The radius (r) must be positive. 
“NOTE| 
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The quadrics and superquadrics functions draw atoms, spheres, ellipsoids, toroids, and hyperboloids of one 
and two sheets. All the primitives in this section are tesselated into polygons. The degree of tesselation is 
controlled by the quadric precision. 





: ; The maximum precision for superquadrics is limited to {60 divisions in each direction. 
NOTE] 





Functions in this section are: 
« RAYquadric_precision(ou,nv) 
a RAYsphereQ) 
a RAYsuperq ellipsoid(x,y,z,expl,exp2) 
a RAYsuperq torus(x,y,z,r,expl,exp2) 
« RAYsuperq hyperi (x,y,z,expl,exp2) 
a RAYsuperq hyper2(x,y,z,expl,exp2) 


When using the quadric and superquadric functions, one bounding volume is implicitly defined around 


NOTE; the entire primitive. 





RAYquadric_precision() 


int RAYquadric_precision(au,ny) 


int nu,ov; 

ou = __ the number of line segments (or points) used to approxmate the 
quadric in the u direction 

ny = __ the number of line segments (or points) used to approxmate the 


quadnc in the v direction 


The RAYquadric_ precision function sets the precision used to render quadrics and superquadrics. The pre- 
cision ts defined by the number of line segments (or points) used to approamate the quadric in both the u 
and v directions. If the values for either direction are less than zero, the function returns RAY ERR ARG, 
otherwise it returns RAY_ERR_OK; the default precision is RAY QUADRIC DEFAULT in both the u and v 


direcuons. 
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RAYsphere(Q) 





void RAYsphere() 





Using the current surface model, the RAYsphere function renders a sphere that is centered at the origin 
and has a unit radius. Its precision is set by the RAYquadric_ precision function. 


Whenever possible, RAYatom should be used in place of RAYsphere. RAYatom is faster and more accu- 
rate than RAYsphere because RAYatom is rendered as a single primitive, while RAYsphere (and all the 
other superquadrics and patches) are tessellated into polygons. RAYsphere should only be used when 
independent scaling is required along each axis of the sphere. 


RAYsuperq ellipsoid( 





void RAYsuperq ellipsoid(xy,z,exp1,exp2) 


float x,y,z,expl,exp2; 

xyz = the radii of the ellipsoid in the x, y, and z directions 
expl = the squareness parameter in the longitudinal direction 
exp2 = the squareness parameter in the latitudinal direction 


The RAYsuperq ellipsoid function renders a superquadric ellipsoid using the current attributes. A super- 
quadric ellipsoid is a single, closed volume that ranges from a cuboid to a spheroid to a pinched object, 
depending on the specified exponents, and is represented mathematically as: 


xcos? ‘(n)cos™*(w) 
-_ ep 
2(n,) = | ycos™ '(n)sin® “(w) 
zsin™ '(n) 
where, 7 and w are the longitudinal and latitudinal angles, respectively. 


Values for n are in the range: -*/2 <= n <= 4/2. 


Values for w are in the range: -r <= w < x. 
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The shape of the ellipsoid can be modified by varying the exponents as follows: 








exp < 1 Square shaped ellipsoids 
exp = 1 Round ellipsoids 
exp = 2. Flat beveled ellipsoids 
exp > 2 Pinched ellipsoids 
All arguments for this function must be greater than or equal to zero. 
NOTEi 
Example: 


The following program fragments render a sphere, ellipsoid, cube, and cylinder, respectively: 


#include  “raylib.h” ‘ 


main() 


{. 


/*render a sphere* / i 
RAYsuperq_ ellipsoid (100.0, 100.0, 100.0, 1.0, 1.0); ' 
/*render an ellipsoid that’s stretched in the y direction®/ 
RAYsuperq_ellipsoid(100.0,200.0, 100.0, 1.0, 1.0); 

/*render a cube*/ 

RAY superq_ ellipsoid( 100.0, 100.0. 100.0,0.01,0.01); 

/*render a cylinder* / 

RAYsuperq_eilipsoid(100.0, 100.0, 100.0,0.0, 1.0); 


RAYexrt(); : 
exrt(O); | 
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RAYsuperq torus() 


void RAYsuperq_torus(x,y,z,r,expl,exp2) 


float x,y,z,r,exp1,exp2; 
xyz = the radu of the toroid ring 
rc = the distance from the center of the torus to the center of the outer 


ting (see Figure 3-1) 
expl = the squareness parameter in the longitudinal direction 


exp2 = __ the squareness parameter in the latitudinal direction 


The RAYsuperq torus function renders a superquadric toroid using the current attributes. The toroid is 
represented mathematically as: 


x(a + cos” '(n)) cos”? ?(w) 
a(nw) =|y(a + cos™'(n)) sin™ “(w) 
zsin™ '(n) 


where, 


and where 7 and w are the longitudinal and latitudinal angles, respectively. 
Values for n are in the range: -w <= < *. 
Values for w are in the range: -# <= w < x, 


If x and y parameters are not the same, the toroid radius is “stretched” in the direction of the larger param- 
eter. The shape of the toroid can be modified in each direction by varying the exponents as follows: 


exp < 1 Square shaped toroids 
exp = 1 Round toroids 

exp = 2 Flat beveled toroids 
exp > 2 Pinched toroids 
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Figure 3-1. A Superquadric Toroid 


RAYsuperq hyper () 


void RAYsuperq_byper! (x,y,z,expl,exp2) 
float x,y,z,explexp2; 


xy = the radii of the xy cross-section of the hyperboloid at z = 0 
z = the height of the hyperboloid when 9 = 45° 

expl = the squareness parameter in the longitudinal direction 
exp2 = __ the squareness parameter in the fatitudinal direction 


The RAYsuperq hyper! function renders a superquadric byperboloid of one sheet using the current attn- 
butes. The hyperboloid is represented mathematically as: 


xsec™ ‘(n)cos™ ?(w) 
a(nw) = | ysec™'(n)sin™ "(w) 


ztan™ '(n) 


where, 7 and w are the longitudinal and latitudinal angles, respectively. 
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Values for 7 are in the range: -r/2 < 9 < #/2. 
Values for w are in the range: - <= w < x. 
The shape of the hyperboloid can be modified by varying the exponents as follows: 


exp <1 Square shaped hyperboloids 
exp = 1 Round hyperboloids 

exp = 2 Flat beveled hyperboloids 
exp > 2 Pinched hyperboloids 


RAYsuperq hyper2( 


void RAYsuperq_hyper2(x,y,z,exp1,exp2) 


float x,y,z,r,expl,exp2; 

xy = the radii of the xy cross-section of the hyperboloid at z = 0 
z = the height of the hyperboloid when 7 = 45° 

expl = the squareness parameters in the longitudinal direction 
exp2 = the squareness parameters in the latitudinal direction 


The RAYsuperq hyper2 function renders a superquadric hyperboloid of two sheets using the current attri- 
butes. The hyperboloid is represented mathematically as: 


xsec? ‘(n)sec?"(w) 
a(nw) = | ysec™ '(n)tan™*(w) 


ztan™ '(n) 


where, n and w are the longitudinal and latitudinal angles, respectively. 
Values for are in the range: -r/2 < 9 < 4/2. 


Values for w are in the range: -*/2 < w < «/2(piece 1), */2 < w < 3*x/2 (piece 2) 


The shape of the byperboloid can be modified by varying the exponents as follows: 


exp <1 Square shaped hyperboloids 
1 Round byperboloids 

2 ‘Fiat beveled hyperboloids 

2 Pinched hyperboloids 


exp 
exp 
exp 


vod 
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A patch is a bounded collection of points used to model a surface. In RAY1ib patches are rendered by first 
specifying a basis matrix and then defining the patch as either: 


1. aset of 16 control points 
2. aset of four corner points with associated tangent and twist vectors 


3. four boundary curves 


The basis matrix determines how the control points will be used to render the patch. Complex surfaces can be 
created by connecting patches. 


Patches in RAYlib are tesselated into polygons based on the current patch precision. 
The patch functions discussed in this section are: 

« RAYpatch geometry3d(xgeom,ygeom,zgeom) 

« RAYpatch precision(ou,nv) 

« RAYput basis(basis,index) 

« RAYselect_patch basis(uindex,vindex) 


Generating Patches 


Bicubic patches are used to create individual surface fragments that can be connected together to form 
complete surfaces of complex objects. Traditionally, patches have been used in the field of computer- 
aided design, for example, ship designers use patches to model ship hulls and automobile designers use 
patches to experiment with different body styles. 


Different types of patches allow varying degrees of control over surface design. Some patches exactly inter- 
polate the control mesh defining the patch (such as Sixteen Point Form patches) while others only loosely 
approximate a surface (such as periodic B-Spline Patches). The type of patch used to represent a surface 
depends on the surface properties required by the designer. 


RAYlib provides users with a set of predefined patch types; Bezier, Hermite, periodic B-Spline and Sixteen 
point form. Users can also define their own patch types with arbitrary properties. 


Patches are described in RAYIib in geometric form and are generated using the technique of forward 
differences because this technique is very fast and generates polygons that can be transformed in the pipe- 
line. Geometric form is a matrix representation of a parametric surface. The equation describing any point 
on a patch ts: 


p(u wv) = U e M . B e M! « yi 


The U and V vectors indicate position in the patch, M is the matrix that defines the characteristic of a patch 
and B is a geometry matrix, which can hold point, tangent or twist information depending on what type of 
patch is being generated. 
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Each of the predefined classes of patches is described below. To define basis matrices for other classes of 
patches, use the RAYput_basis() function discussed later in this section. 


Patches are always generated as polygonal meshes and are implicitly enclosed by one bounding volume. 
Once the desired shape is obtained, users can employ sophisticated lighting models and texture mapping to 
create photorealistic complex objects. 

Texture mapped patches are currently not available. 


NOTE 


Bezier Patches 


Bezier patches are formed from a mesh of 16 control points. The four corner points actually lie on the 
patch; the other control points are approximated. The Bezier surface has a characteristic polyhedron of 16 
points. The matrices defining the patch are: 


Xa Xp Soe Bis Yo You Yos Yxz 25-200 20 ZG 
or 05 tog X15 or Yos Yoo Yi3 Z01 205 209 713 
02 X06 T10 X14 02 Yoo Yio Yi4 Z02 206 210 214 
Xo3 Xo7 Tu X45 03 Yor Vis Vis Z03 Zo7 Z11 215 


Hermite Patch 


A Hermite patch is defined by the following matrix 


v v v v v v 
00 Xo, *00 *or oo Yor Yoo You Zoq Zo, 700 701 

v v v v v v 
to *11 410 711 io Yu Yio Yu Z10 211 Z10 Z1 
u u uy uy “ u uv uv u u uy uy 
00 01 *00 *o1 00 Yor Yoo Yor Z00 701 200 701 
u a uy uy és a“ uv uy “ u uy uv 
to *11 T1090 Fa2 10 Yu Yio Var 210 21 Z10 21 


Po" is the derivative of the point with respect to the parametric variable u; P” is the derivative of the point 
NOTE! with respect to v; P#” is the derivative of the point with respect to u and v. 





The matrix is split into four quarters. The upper left quarter defines the four corner points; the lower left 
quarter contains the u tangent vectors at the four corner points; the upper right quarter contains the v 
tangent vectors at the four corner points; the lower right corner contains the twist vector. If twist is set to 
zero, then the patch is a Ferguson, or F-patch. This type of patch can only have first-order continuity with 
adjacent patches. An F-patch ts easier to specify than a fully specified Hermite patch because the twist 
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vectors can be difficult to compute. 


B-Spline Patch 


The B-Spline surface is defined by a characteristic polyhedron, where all of the points fall within the convex 
hull. The patch weakly approximates the polyhedra and local deformations of control points affect only 
local regions of the patch. The particular type of B-Spline used here is termed periodic, which refers to the 
symmetry of the blending function used to generate the patch. 


Sixteen-Point Form Patch 


The Sixteen-Point Form patch is defined as a patch whose 16 control points actually lie on the patch. 
Sixteen-Point Form patches are easy to specify, particularly if the input geometry for the patch can be 
obtained from a device like a 3D digitizer that can accurately interpolate the points on an object. 


Sixteen-Point Form patches can be contrasted with Bezier patches, where only the four corner points actu- 
ally lie on the patch. The control points for Sixteen-Point Form patches are interpolated, whereas the con- 
trol points for Bezier patches are approximated. Sixteen-Point Form patches do not require input of 
tangent or twist vectors. 


RAYpatch_ geometry 3d() 


void RAYpatch geometry 3d(xgeom,ygeom,zgeom) 
RAYmatrix xgeom,ygeom,zgeom; 


xgeom,ygeom,zgeom = a set of 3D control points 


The RAYpatch geometry 3d function renders a 3D surface patch using the current basis matrix and the 
current patch precision. 


The shape of a 3D surface patch is defined by a set of user-specified 3D control points. The surface patch 
is rendered using the current surface model. 


| One bounding volume is implicitly defined around the entire primitive. 
| NOTE| 
: ‘ 


1 
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int RAYpatch precision(nu,ayv) 
int ou,nv; 


ou,nyv = the curve’s precision in the u and v directions 





The RAYpatch precision function specifies the number of points, lines, or polygons used to represent seg- 
ments of a surface patch. The precision is specified for both the u and v directions and can be a different 
value for each direction. The arguments are specified as integers and must be greater than or equal to 
zero. Remember, the higher the number (nu,nv), the smoother the patch, but the longer it takes to render. 
If the arguments mu,nv are less than zero, the function returns RAY_ERR_ARG, otherwise it returns 
RAY_ERR_OK. The default patch precision is RAY PATCH DEFAULT in both the u and v directions. 


RAYput_basis() 





int RAYput_basis(basis,index) 
RAYmatrix basis; 


int index; 
basis = a matrix of 16 floating point numbers 
index = the index number associated with the basis matrix 





The RAYput basis function defines a 4x4 basis matrix and an associated index number, that can subse- 
quently be used in rendering patches. The index numbers are defined by the following constants: 


RAY_USER BASIS 0 
RAY_USER BASIS” 
RAY_USER_BASIS_7 


At initialization, the first four basis matrices contain the matrix definitions for Bezier, Hermite, B-spline 
and Sixteen-point patches, respectively. Unless you wish to overwrite these matrices, the index argument 
passed to RAYput_basis() should range from RAY USER BASIS 4 to RAY_MAX_ BASIS - 1. 
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If index is less than zero or greater than or equal to RAY_MAX_BASIS, this function returns a value of 
RAY_ERR_ARG, otherwise this function returns a value of RAY_ERR_OK. 


Once defined, the basis matrix is selected by passing its associated index to the RAYselect_patch basis 
function. 


RAYselect_patch_basis() 


int RAYselect _patch_basis(uindex,vindex) 
int uindex,vindex; 
uindex = the index to the basis matrix for the u direction 


vindex = the index to the basis matrix for the v direction 


The RAYselect_patch basis function selects the basis matrices to be used in drawing a surface patch. A 
basis matrix is selected for both the u and v parametric directions of the patch. The basis matrices and 
their indices must have been previously defined by RAYput_basis. If uindex or vinder are less than zero or 
greater than or equal to RAY_MAX BASIS, RAYselect_patch basis returns RAY_ERR_ARG, otherwise 
this function returns a value of RAY_ERR_OK. 


(At present, uindex and windex must be set to the same value. 
NOTE! 
t 


Example: 


Generate a viewport with a shaded Bezier bicubic patch. 





#include “raytib.h” 
#detine Pt 3.14159265358979323846 


RAYmatrix GX = { 
-100.0, -100.0, -100.0, -100.0, | 
-50.0, -50.0, -50.0, -50.0, 
50.0, 50.0, 50.0, 50.0, 
100.0, 100.0, 100.0, 100.0 


RAYmatrix GY = { 








-100.0, -50.0, 50.0, 100.0, 
-100.0, -50.0, 50.0, 100.0, 
-100.0, -50.0, 50.0, 100.0, 
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aE continued —~\ 
: \ 


/ \ 


-100.0, -50.0, $0.0, 100.0 \ 


{ 
1 
t 


RAYmatrix GZ = { 

H 0.0, 30.0, 70.0, 110.0, 
20.0, 0.0, 80.0, 90.0. 

30.0, -30.0, 40.0, 60.0, 
60.0, 80.0, 90.0, 20.0 


} 
main(arge,argv) 
int arge; 
H char **argy; 
| | 
| int precu, precy; 
RAYlight_source light; 


RAYsurtace_model poly surface; 


it (RAYinit() exit(-1); 





[2s set patch precision som £S7 

precu = 13; i 
| precy = 13; 

4 

/* - setup surtace characteristics .. °/ 


poly _surtace.d red = 0.7; 
poly _surtace.d green = 0.3; 
poty_surtace.d blue = 0.2; 


t 

| 

| poly _surtace.exp = 1.0; 

| poty_surtace.specularity = 1.0; 
| poly surface.transparemt = 0.0; 
| 


poty_ surface reflectivity = 0.0; 
poly _surtace.refraction index = 1.0; 
RAYput_surface_modei( &poty_surtace ); 


RAYshade_mode( RAY TRACE ); 
/* .— make drop shadow — */ 


: RAY put _viewport( 290 + 20, 690 + 20, 80 + 20, 400 + 20); 
: RAY clear viewport( 0.1, 0.15, 0.5, 0.0): 


/* — create viewport and projection a] 





RAY put vewport( 290, 690, 80, 400 ); 


RAYpersp project(30.0 . 1 25, 1 0, 2048.0): 
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conanued ~~ 


RAYlookup_view(185.0, 185.0, 185.0, 0.0, 0.0, 0.0, 0.0); 
[* = setup light source — */ 


RAYclear_viewport( 0.2, 0.3, 0.7, 0.0 ); 
RAYbackground_color( 0.5. 0.7, 0.9 ); 
RAYlight_ambient( 1.0, 1.0, 1.0); 
RAYambient_intensity( 0.3 ): 

light.nx = 1.0; 

light.ny = -0.5; 

light.nz = 1.0; 

lignht.c = 0.7; 

light.g = 0.7; 

lignht.b = 0.7; 


RAY put _light_source( RAY LIGHT DIRECT, 1, Slight ): 
RAYlight_switch( RAY_LIGHT_ DIRECT, 1, RAY_ON); 


RAYpatch_precision(precu.precy); 
RAY select _patch basis(RAY BEZIER BASIS, RAY 8EZIER_BASIS); 


RAY scale(0.4, 0.4, 0.4); 

fee display shaded patch — °/ 
RAYpatch geometry 3d(GX.GY.GZ); 
RAYtrace(): 


RAY exit(); 
ext); 
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Bounding Volumes 


Bounding volumes are 3D extents used to group objects that are near each other. A bounding volume is 
defined as the extents of the smallest cube that encloses all the objects being grouped. Bounding volumes 
are parallel to each coordinate axis in Viewing Space. 


All objects defined after a RAYopen bounding volume function call and before its corresponding 
RAYclose_bounding volume function call are included in the same bounding volume. When a bounding 
volume is encountered while tracing a given ray, the bounding volume is tested for intersection with that 
ray. The contents of the bounding volume are tested for intersections with the ray if, and only if, the ray 


intersects the bounding volume. Bounding volumes can be nested to further improve performance. 


Although they are not required, bounding volumes are highly recommended for any RAYIlib program, 
because they can significantly reduce the time it takes to ray trace a given scene. Proper selection of 
bounding volumes is largely trial and error, however, using the following guidelines should improve render- 
ing time: 


1. If an entire scene fits in a viewport, bound the entire scene. 


2. Nest bounding volumes into a hierarchy of scene, groups of objects, objects, groups of primitives. 
Each of these levels can be further nested if they are sufficiently complex. 


3. Bounding volumes work best when they envelope groups of 7 t6 20 objects (an object may be a 
nested bounding volume or a primitive). 


4. Bounding volumes work best when the objects they bound are grouped closely together in viewing 
space. The smaller the volume, the better the performance. 


5. Do NOT bound individual atoms (RAYatom), but try to collect those that are close to each other. 
Higher level objects, such as superquadrics and patches, are tessellated into simpler triangles by 
RAYIib. Also, RAYlib automatically creates a bounding volume for each superquadric and patch. 


The effort involved in generating good, tight, nested bounding volumes will more than pay for itself with 
significantly reduced rendering times. 
Functions in this section are: 

a RAYopen bounding volume() 

« RAYclose_ bounding volume() 


RAYopen_bounding volume() 





int RAYopen bounding volume() 





This function opens a bounding volume. The extents of the bounding volume are defined by the cumulative 
extents of each object defined up to the matching RAYclose_ bounding volume. Bounding volumes can be 
nested up to RAY MAX _BVOL_NEST levels deep. Upon successful completion, this function returns a 
value of RAY_ERR_OK If a call exceeds the madmum nesting level, RAY MAX BAD 8VOL is returned. 
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RAYclose_ bounding volume() 


int RAYclose_ bounding volume() 


Bounding Volumes 


This function closes a bounding volume opened in a matching RAYopen_bounding volume call. Once this 
function is called no other objects are considered as part of this bounding volume, and the current extents 

of the bounding volume are saved. Upon successful completion, this function returns a value of 
RAY _ERR_OK. If you attempt to close more bounding volumes than are opened, RAY_ERR_BAD_8VOL 
is returned. 


Example: 


ii 


/ 


{ 





# include “raylib.n” 


main( 


{ 


/* raylid initialization */ 
it (RAYinit) exit(100); 


RAYopen_bounding_volume(); 
RAYpoly point 3d(xt.y1.z1); 
RAY poly point 3d(x2,y2,z2); 
RAY poly _point_3d(x3,y3,z3); 
RAY poly point 3d(x4,y4,24); 
RAYpoty close(); 


RAY close bounding volume (); 


RAYtrace(); 
RAYexit(); 
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Transformations 


The list below describes the three major types of transformations: Modeling, Viewing and Projection. 


= Modeling transformations manipulate the Object Coordinate System with respect to the World 
Coordinate System. Objects are first defined in their own space, the Object Coordinate System, and 
then placed in the World Coordinate System by applying the modeling transformations (rotate, 
translate, and scale). The Object Coordinate System can be the same as the World Coordinate Sys- 
tem, thus eliminating the transformation from Object to World Space. The World Coordinate Sys- 
tem is a right-hand system with y to the right, z up, and x out of the page (see Figure 3-2). 


« Viewing transformations transform World Space to Eye Space. The Eye Coordinate System is a 


right-hand system with x to the right, y up, and z out of the page. The eye is at the origin and the 
viewing direction is down the negative z axis (see Figure 3-3). 


= Projection transformations map eye space into the Screen Coordinate System. The origin of the 
Screen Coordinate System is in the lower left corner with x to the right and y up (see Figure 3-4), 


Primitives that are not transformed by the current transformation matrix, such as viewport definitions, are 
specified in the Pixel Coordinate System. The origin of the Pixel Coordinate System is in the upper left 
corner with x to the right and y down (see Figure 3-5). 


Transformation Matrices 


There is a matrix stack and current matrix that can be operated on. The stack contains the Modeling and 
Viewing transformations. Objects are transformed by the current Modeling and Viewing (MV) matrix. 
Viewing commands replace the current MV matrix with the specified viewing matrix. Modeling functions 
cause the current MV matrix to be premultiplied by the matrix representing the specified transformation. 
For this reason, transformations should be specified in the reverse order in which they will be applied. 
Typically, transformations are specified in the following order: 


1. Projection transformations 
2. Viewing transformations 
3. Modeling transformations 


Object vertices and light positions are transformed by the current set of transformation matrices. Push and 
pop functions can be used to localize operations by saving and restoring transformations. 
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x (OUT OF PAGE) 


Figure 3-2. World Coordinate System 





Az (EYE AT 0. 0, 0, LOOKING 0, 0, -2z) 


Figure 3-3. Eye Coordinate System 


RAYiib Functions 3-27 


Figure 3-4. Screen Coordinate System 


Figure 3-5. Pixel Coordinate System 
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The RAYIib Projection Transformation functions define the viewing volume and type of projection. The 
projection transformation maps Eye Space to Screen Space. RAYIib provides the following types of projec- 
tions: 


s Perspective pyramid 
« Perspective window 
Functions in this group are: 
« RAYpersp project(foy,aspect,near,far) 
s RAYwindow _project(left,right,bottom,top,near far) 


RAYpersp_project() 


void RAYpersp_project(fovy,aspect,near far) 


float fovy,aspect,near,far; 

fovy = the field-of-view angle in the y direction of the Eye Coordinate System 

aspect = the ratio of the x and y dimensions of the Eye Coordinate System 

nearfar = the distances form the origin to near and far planes along the view vector. 
These arguments are present only for compatibility with P!Clib and are 
ignored by RAYIlb. 


RAYpersp_ project defines a 3D perspective viewing pyramid by specifying the field-of-view angle, fovy, in 
the y direction and the aspect ratio of the x and y directions of the Eye Coordinate System. The fovy and 
aspect parameters determine the size of the projection frustrum. The aspect ratio of the projection frustum 
should match the aspect ratio of the current viewport in order to display data without distortion. 


The near and far arguments are present only for compatability with PIClib and are ignored by RAYIib. 


| NOTE 


eee 
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RAYwindow_project( 





void RAYwindow project (left,right,bottom,top,near far) 
float left,right,bottom,top,near,far; 


left,right,bottom,top = the position and size of the viewing window in the near clipping 
plane, defined in the x and y dimensions of the Eye Coordinate Sys- 
tem : 

near = the distances from the eye to the near plane. This argument is used 
to position the projection window. 

far = included only for PiClib compatability. This argument is ignored by 
RAYlib. 





The RAYwindow_project function defines a 3D perspective projection by specifying a rectangular frustum 
in the near plane. The parameters /eft, right, bottom and top define the position and size of the viewing win- 
dow in the near plane. These are specified in the x and y directions of the Eye Coordinate System. 


| The near and far arguments have no meaning other than positioning the projection window. These argu- 
_NOTE| ments are included for compatability with PiClib and are otherwise ignored. 


' 
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Viewing Transformations map World Space into Eye Space, given the user’s view specified by an eye posi- 
tion and a view direction in the World Coordinate System. RAYIib provides four viewing functions for speci- 
fying the viewpoint and viewing direction: 


« RAYlookat_view(vx,vy,vz,px.py,pz,twist) 
« RAYlookup_view(vx,vy,vz,px,py,pz,twist) 
« RAYcamera_view(x,y,z,pan,tilt,swing) 

a RAYpolar_view(dist,azim,inc,twist) 


The viewing transformations are kept on the transformation stack and are pre-multiplied by the modeling 
transformations as they are defined. Therefore, the viewing transformations must be specified before any 
modeling transformations are applied. 


RAYlookat_view, RAYlookup view, RAYcamera_view, and RAYpolar view all rep/ace the current transfor- 
mation with the specified viewing matrix. To preserve the current modeling and viewing transformation, 
use the RAYpush _traasform command. 


| All rotations discussed in this section follow the nght-hand rule, unless otherwise noted. All rotations 
id are specified in degrees. 
RAYlookat_view() 


void RAYlookat_view(vx,vy,vz,px,py,pz,twist) 
[oat vx,vy,vZ,pXx, py, pz,twist; 


YX,VY,VZ = the coordinates of the viewpoint 

Px, py, pz = the coordinates of the reference (at) point 

twist = the rotation about the view vector (the -z axis of the Eye Coordinate 
System) 


RAYlookat_view defines a viewpoint and a reference (lookat) point in World Coordinates. The viewpoint 
is at (vx, vy, vz) and the reference point is (px, py, pz). These two points define the view direction or mew 
vector. The twist angle specifies a rotation about the view vector (directed from the viewpoint to the reter- 
ence point). The view vector defines the -z axis of the Eye Coordinate System. 
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| RAYlookat_view maintains the y axis of the World Coordinate System as the up vector. 





RAYlookup_view() 


void RAYlookup_view(vx,vy,vz,px,py,pz,twist) 
float VXx,Vy,VzZ,pXx,py,pz,twist; 


VX,VY,VZ = the coordinates of the viewpoint 
Px, py, pz = the coordinates of the reference (at) point 
twist = the rotation about the view vector, (the -z axis of the Eye Coordinate System) 





The RAYlookup_view function specifies the viewpoint and view direction with a from point and an at point 
in the World Coordinate System. These two points define the view direction or view vector. The twist angle 
specifies a rotation about the view vector (directed from the viewpoint to the reference point). The 
RAYlookup_view transformation ensures that the +y (up) vector of Eye Space and the +z (up) vector of 
World Space form an acute angle. If the view direction is (0,0, +z), then the results are the same as if 
theRAYlookat_view function had been used. 





RAYlookup_view maintains the z axis of the Worid Coordinate System as the up vector. 
NOTE! 





RAYcamera_view() 


void RAYcamera_view(x,y,z,pan,tilt,swing) 
float x, y,z,pan,tilt,.swing; 


XYZ = the x, y, and z coordinates of the viewpoint 

pan = the left-hand rule rotation about the y axis of the Camera Coordinate System 
tilt = the left-hand rule rotation about the x axis of the Camera Coordinate System 
swing = — the left-hand rule rotation about the z axis of the Camera Coordinate System 
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RAYcamera_view defines a viewing transformation in terms of pan, tilt, and swing angles. The arguments 
to this function define a viewpoint (x,y,Z) and specify a view direction by applying a pan degree rotation 
about the y axis, a n/t degree rotation about the x axis, and a swing degree rotation about the z aus of the 
Camera Coordinate System. 


In its initial orientation, the x, y, z axes of the Camera Coordinate System are parallel to the -x, z, -y axes of 
the World Coordinate System. The eye is positioned at the origin of the Camera Coordinate System 
(defined by x, y, z) and the viewing vector is the positive z axis of the Camera Coordinate System. The 
orientation of the view vector is determined by the pan, alt and swing parameters. See Figures 3-6 and 3-7. 
Note that the view vector in Figure 3-7 points toward the origin. 


| 


The Camera Coordinate System is a left-hand system and all rotations in it are left-hand rotations. 


le 






WORLD COORDINATE 
SYSTEM 


CAMERA COORDINATE 
SYSTEM 


\— VIEW VECTOR 


Figure 3-46. RAYcamera_view(100.0, 100.0, 0.0, 0.0, 0.0, 0.0) 
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WORLD COORDINATE 
SYSTEM 


CAMERA COORDINATE 
SYSTEM 





VIEW VECTOR 


Figure 3-7, RAYcamera_view(100.0, 100.0, 0.0, 45.0, 0.0, 0.0) 


RAYpolar_view( 


void RAYpolar_view(dist,azim,lnc,twist) 
float dist,azim,inc,twist; 


dist = the distance from the viewpoint to the origin of the World Coordi- 
nate System 

azim = the azimuthal angle of the viewpoint in the xy plane measured from 
the y aus 

inc = the incidence angle of the viewpoint in the yz plane measured from 
the z axis 

twist = the rotation about the view vector (the -z axis of the Eye Coordinate 
System) 
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The RAYpolar_view function defines the viewpoint and direction in Polar Coordinates. The dist parameter 
is the distance from the viewpoint to the origin of the World Coordinate System. The azim parameter is the 
azimuthal angle in the xy plane, measured from the y axis. The inc parameter is the incidence angle in the 
yz plane measured from the z axis. The twist parameter specifies a rotation about the view vector. The view 
vector is directed from the viewpoint to the origin of the World Coordinate System and defines the -z axis 
of the Eye Coordinate System. 
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The Modeling Transformations rotate, translate, and scale objects relative to the World Coordinate Sys- 
tem. Modeling functions cause the current MV matrix to be premultiplied by the matrix representing the 
specified function. Because of this, modeling transformations are applied to all objects drawn after the 
modeling transformation is requested. The current Modeling and Viewing matrix can be saved with the 
RAYpush transform function and restored with the RAYpop_ transform function. 


This section describes the following modeling transformation functions: 


Rotation Functions 

a RAYrotate_x(x) 

« RAYrotate_y(y) 

« RAYrotate_2z(z) 

= RAYrotate_vector(x,y,z,nx,ny,nz,angle) 
« RAYput rotate _dx(dx) 


Translation Functions 

« RAYtranslate_x(x) 

« RAYtranslate_y(y) 

« RAYtranslate_z(z) 

« RAYtranslate(x,y,z) 

« RAYput translate _dx(tx) 


Scaling Functions 

« RAYscale_x(x) 

m RAYscale y(y) 

s RAYscale_z(z) 

we RAYscale(xy,z) 

« RAYput scale dx(sx) 


a RAYput rotate dy(dy) 
« RAYput rotate _dz(dz) 
« RAYrotate_dx() 
« RAYrotate dy() 
« RAYrotate_ dz() 


« RAYput translate dy(ty) 
« RAYput translate dz(tz) 
« RAYtranslate_dx() 
« RAYtranslate_dy() 
« RAYtranslate dz() 


a RAYput scale _dy(sy) 
« RAYput scale dz(sz) 
a RAYscale_dx() 
s RAYscale_dy() 
a RAYscale_ dz() 


| | All modeling commands operate with respect to the World Coordinate System. 


| NOTE} 
1 i 
1 
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Rotation 


Objects may be rotated with respect tox or y or z or an arbitrary axis. All rotations follow the right-hand 
rule. Positive rotations are counterclockwise when looking from the positive axis toward the origin (see Fig- 
ure 3-8). 


Rotations may be absolute or incremental. Absolute rotations rotate about the x or y or z axis by x y, andz 
degrees. Also, arbitrary axis rotations allow you to specify an axis of rotation with a point, x,y,z, a direction, 
nxny,nz, and an angle §. This produces a rotation of @ degrees about the specified axis with the center of 
rotation at xy,z. 


Incremental rotations rotate about the xy, or z axis by a prespecified Ar, Ay, and Az degrees. 


Positive degrees cause counterclockwise rotation; negative degrees cause clockwise rotation. 
' NOTE 
1 


The rotation functions are: 


« RAYrotate_x(x) = RAYput rotate _dy(dy) 
« RAYrotate_y(y) = RAYput rotate _dz(dz) 
« RAYrotate_z(z) « RAYrotate_dx() 
« RAYrotate_vector(x,y,z,nx,ny,nz,angle) « RAYrotate_dy() 
« RAYput rotate_dx(dx) « RAYrotate_dz() 
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EYE 
y 
i 
(90° ROTATION ABOUT 
THE y-AXIS) (FINGERS CURL COUNTER 
x CLOCKWISE FROM THE EYE) 


Figure 3-8. Right-Hand Rule Rotation 


RAYrotate Functions 





void RAYrotate_x(x) 
float x 


x = the angle of rotation about the x axs 


void RAYrotate_y(y) 
float y; 


y = the angle of rotation about the y axis 


void RAYrotate_z(z) 
float z; 


z = the angle of rotation about the z aus 


The RAYrotate functions (RAYrotate_x, RAYrotate_y and RAYrotate 2z) rotate objects by a specified angle 
about the x or y or z axis. The angle is specified in degrees according to the right-hand rule. 
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RAYrotate_vector() 


void RAYrotate_vector(x,y,2,nx,ny,nz,angle) 
float x,y,2z,nx,ny,nz,angie; 


xy zox,nynz = the point (xy,Z) and direction (nxny,nz) that define the axis about 


angle 


which the object will rotate 
= the angle of the rotation expressed in degrees 


The RAYrotate_ vector function rotates objects by a specified angle about an arbitrary axis. The axs of 
rotauon is defined by a point and a direction as shown below: 
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(10.0, 0.0, 0.0) UNROTATED SPHERE (00. 00, 0 0) 






(0.0. -1.0, 0.0) 


=e ROTATED SPHERE (100,00. - 100) 


) , 


ae 4 


Figure 3-9. Arbitrary Axis Rotation 
(RAYrotate_vector( 10.0,0.0,0.0,0.0,-1.0,0.0,90.0); 
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Example: 


The following example demonstrates how to specify a rotation of 90° about the vector defined by the point 
[10.0, 0.0, 0.0] and the direction [0.0, 1.0, 1.0]. 


RAY rotate _vector( 10.0, 0.0, 0.0, 0.0, 1.0, 1.0, 90.0); 


RAYsphere(); /* draw a unit sphere at the origin */ 








} 
x 
Oe oes eg ee ee ee, 
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void RAYput rotate _dx(dx) 
float dx; 


dx = the incremental angle of rotation, in degrees, about the x as 


void RAYput_ rotate _dy(dy) 
float dy; 


dy = the incremental angle of rotation, in degrees, about the y axis 


void RAYput rotate dz(dz) 
float dz; 


dz = the incremental angle of rotation, in degrees, about the z axis 





The RAYput rotate d functions ( RAYput rotate dx, RAYput_rotate dy and RAYput rotate dz) specify 
the 4 rotation about each axis. Objects can then be rotated in increments about a World Space axis (x, y, 
of Z) using the RAYrotate d functions. 
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void RAYrotate_dx() 
void RAYrotate_dy() 
void RAYrotate_dzQ 


The RAYrotate_d functions (RAYrotate dx, RAYrotate_dy and RAYrotate_ dz) rotate objects about the x, 
y, and/or z axis using a predefined incremental rotation. Before using any of the RAYrotate_d functions, 
be sure to specify the incremental angle with one of the RAYput_rotate_d functions. 


Transiation 


Objects can be translated independently in x or y or z or in xyz. There are two types of translations: absolute 
and incremental. Absolute translations are applied along x or y or z. Incremental translations are applied 
along the x or y or z axis by a specified Ar, Ay and Az. 


The translation functions are: 


a RAYtranslate_x(x) « RAYput transiate_dy(ty) 
« RAYtraaslate_y(y) = RAYput translate _dz(tz) 
s RAYtranslate_z(z) « RAYtranslate_dx() 

s RAYtranslate(x,y,z) « RAYtransiate_dy() 

« RAYput translate dx(tx) « RAYtranslate_dz() 
RAYtranslate Functions 


void RAYtranslate(x,y,z) 
float xy,z3 


XYZ =  thex,y, z translation 


void RAYtranslate_x(x) 
float x; 


x = the x translation 


void RAYtranslate_y(y) 
float y; 
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y = the y translation 


void RAYtranslate_z(z) 
float z; 


z = the z translation 


The RAYtranslate functions (RAYtranslate, RAYtranslate_x, RAYtranslate_y and RAYtranslate_z) apply 
a translation along x or y or z to the current transformation matrix. 


RAYput transiate_d Functions 


void RAYput_translate_dx(tx) 
float oc 


Xx = the incremental translation in x 


void RAYput_transiate_dy(ty) 
float ty; 


ty = the incremental translation in y 


void RAYput translate _dz(tz) 
float tz; 


tz 7 the incremental translation in z 


The RAYput translate d functions (RAYput translate dx, RAYput translate dy and 
RAYput translate dz) specify the delta translation along each axis. Objects can then be translated in 
increments along a World Space axis (x,y, or z) using the RAYtranslate_d functions. 


RAYtransiate d Functions 


void RAYtranslate dx() 
void RAYtranslate dy() 
void RAYtranslate dz() 
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The RAYtranslate_d functions (RAYtranslate_dx, RAYtranslate_dy and RAYtranslate_dz) translate the 
objects along the x or y or z axis by a predefined incremental translation. Before using any of the 
RAYtranslate_d functions, be sure to specify the incremental angle with one of the RAYput translate d 
functions. 


Scaling 
Objects can be scaled independently about x or y or z or about xyz, simultaneously. Scale commands can 
shrink (sx < 1), expand (sx > 1), and mirror (sx < 0) objects. 


There are two types of scaling transformations: absolute and incremental. Absolute scaling is applied about 
xoryorz. Incremental scaling is applied about the x or y or z axis by a specified Ar, Ay, and Az. 


The scaling functions are: 


= RAYscale_x(x) « RAYput scale _dy(sy) 
# RAYscale_y(y) « RAYput scale _dz(sz) 
« RAYscale_z(z) # RAYscale_dx() 
« RAYscale(x,y,z) a RAYscale_dy() 
« RAYput_scale_dx(sx) « RAYscale_dz() 


RAYscale Functions 


void RAYscale(x,y,z) 
Moat x,y,z; 


XYZ = the x, y, and z scaling factors 


void RAYscale_x(x) 


float x; 

x = the x scaling factor 
void RAYscale_y(y) 

Moat y; 

y = the y scaling factor 


void RAYscale_z(z) 
float z; 


Ml 


z the z scaling factor 
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, Acommon mistake is to cali RAYscale with only one argument. Be sure to supply x, y and z scaling fac- 
a tors even if uniform scaling is desired. 


et 


The RAYscale functions (RAYscale, RAYscale x, RAYscale_y and RAYscale_z) reduce, enlarge, and mirror 
objects by scaling the object’s x or y or z coordinates by the scaling factors x, y, and z, respectively. Objects 
can be scaled about one axis only or about all three axes. 





: ! Positive scaling factors larger than / expand the object; less then /, reduce the object. Negative scaling 
NOTE! factors mirror the scaled object across an axis. 
ree) 


RAYput_ scaie_d Functions 





void RAYput scale _dx(sx) 
float sx; 


sx = the incremental scaling factor in x 


void RAYput_scale_dy(sy) 
float sy; 


sy = the incremental scaling factor in y 


void RAYput scale _dz(sz) 
float sz; 


sZ = the incremental scaling factor in z 





The RAYput scale d functions (RAYput scale dx, RAYput scale _dy and RAYput scale dz) specify the 
delta scaling factor about each axis. Objects can then be scaled about a World Space axis (x, y or 2) using 
the RAYscale_d functions. 


RAYscale_d Functions 





void RAYscale_dx() 
void RAYscale_dy() 
void RAYscale_dz() 
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The RAYscale_d functions (RAYscale_dx, RAYscale_dy and RAYscale_dz) scale the objects in x or y or z by 
a predefined incremental scale factor. Before using any of the RAYscale_d functions, be sure to specify the 
incremental angle with one of the RAYput_scale_d functions. 


Example: 
The following code fragment illustrates the use of the incremental scaling and rotation functions. 


, 
RAYpersp project( 45.0, 1.25, 1.0, 1000.0); 


RAYiookup_view( 150.0, 150.0, 150.0, 0.0, 0.0, 0.0, 0.0); | 


RAYput scale dx (3.0); /* set the incremental x scale value */ 
RAYput_rotate d2z(20.0); /* set the imcremental y rotation value */ | 


for (i = O; i < MAX_ITERATIONS; i + +) { 


RAYrotate_dz(); 
RAYscale_dx(); 


RAYpatch geometry 3d(GX.GY.G2); 
RAYtrace(); i 





RAYswap_butter(): 
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Transformations - Control Functions 


The Transformation Control functions manipulate the modeling and viewing transformation stack by push- 
ing and popping, pre- and postmultiplying, and loading or retrieving matrices. 

| ' RAYlib does not have the projection matrix stack that P!Clib has. 

' NOTE| 
! } 


: 
' 


The modeling and viewing transformation matrix is applied as follows: 


Co Co Co Co 


pred leo cuca ca] * Pye 


Cy Cy Cy C33 


Modeling and Viewing Transformation Control 


The Modeling and Viewing Transformation Control functions operate on the current MV (Modeling and 
Viewing) matrix and MV stack containing the modeling and viewing transformations. These functions arc: 


« RAYget inverse transform(matrix) : = RAYpush transform() 

= RAYget_oormal_transform(matrix) = RAYpop transform() 

« RAYget transform (matrix) = RAYput transform(matrix) 

® RAYpremultiply transform (matrix) « RAYput identity transform() 


« RAYpostmultiply transform (matrix) 


RAYget_inverse transtorm( 





int RAYget inverse transform(matrix) 
RAYmatrix matrix; 


matrix = indicates where to store the inverse of the current MV transforma- 
tion matrix 
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The RAYget_inverse_transform function returns the inverse of the current MV transformation matrix. The 
inverse is computed on the host from the current MV matrix obtained from the Pixel Machine. This func- 
tion does not change the MV transformation stack or current transformation matrix. 


RAYget_inverse_transform returns RAY_ERR_INVERSE if the matrix is singular (not invertable), and 
RAY_ERR_OK if successful. 


RAYget_normal_transtorm( 





void RAYget_normal transform(matrix) 
RAYmatrix matrix; 


matrix = indicates where (o store the normal transformation matrix 


The RAYget_normal_ transform function returns the normal vector transformation matrix. The normal vec- 
tor transformation matrix is the inverse transpose of the upper 3x3 submatrix of the current transformation 
matrix. This function does not change the MV transformation stack or current transformation matrix. 


RAYget_transtorm() 





void RAYget_transform( matrix) 
RAYmatrix matrix; 


matrix 7 indicates where to store the current transformation matrix 


The RAYget_ transform function returns the current 4x4 modeling and viewing transformation matrix. This 
function does not change the MV transformation stack or current transformation matrix. 


RAYpremultiply_transtorm() 


void RAYpremultiply transform(matrix) 
RAYmatrix matrix; 


matrix 7 a user-defined 4x4 matrix 
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The RAYpremultiply transform function premultiplies the current MV transformation matrix bya 
specified matrix. The result becomes the current MV matrix. 


RAYpostmuitiply_transtorm(Q 





void RAYpostmultiply transform(matrix) 
RAYmatrix matrix; 


matrix = a user-defined 4x4 matrix 





The RAYpostmuiltiply transform function postmultiplies the current MV transformation matrix bya 
specified matrix. The result becomes the current MV matrix. 


RAYpush_transtorm( 





void RAYpush_transform() 





The RAYpush transform function places a copy of the current MV transformation matrix on top of the 
stack. (The stack is not changed if it is full.) The MV transformation stack can be 
RAY_MAX_TRANSFORM levels deep. 


This function is useful for saving the current transformation on the matrix stack, modifying this transforma- 
tion temporarily, and then restoring its original contents by popping the transformation stack with 
RAYpop transform. 


RAYpop _transtorm( 





void RAYpop _transform() 





The RAYpop transform function replaces the current transformation matrix with the transformation 
matrix on top of the MV stack. If the MV transformation stack is empty, RAYpop transform has no cffect. 
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Example: 


The following code fragment illustrates the use of the push and pop operations on the transformation stack. 


| RAYpersp project( 45.0, 1.25, 1.0, 1000.0): 
RAYlookup_view( 150.0, 150.0, 150.0, 0.0, 0.0, 0.0, 0.0); 


RAYpush _transform(): /* save the original coordinate systens */ 
| RAYtransiate(10.0, 10.0, 10.0); 
RAYrotate x (90.0); i 
| RAYsuperq_torus(50.0, 50.0, 50.0, 90.0, 1.0, 2.0); 
RAYpop transtorm(); _/* restore the original coordinate system $/ 


RAYsphere(); { 
} ! 


eee 


RAYput_transform( 








void RAYput_transform (matrix) 
RAYmatrix matrix; 


matrix = a user-defined 4x4 matrix 





The RAYput_ transform function loads a specified 4x4 matrix into the current MV transformation matrix. 
This function replaces the current MV transformation matrix with the specified matrix. [f you need to save a 
copy of the current transformation matrix on the stack, use RAYpush transform first. 


RAYput identity transtorm( 





void RAYput identity transform() 
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The RAYput identity transform function places an idenaty matrix into the current MV transformation 
matrix. This function replaces the current MV transformation matrix with the specified matrix. If you need 
to save a copy of the current transformation matrix on the stack, use RAYpush transform first. 


The identity matrix is of the form: 
1000 
0100 


0010 
0001 
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The viewport functions allows you to define an area on the screen that displays the rendered image. 
Viewports are defined by specifying the four limits of the rectangular area in screen units. Depending on 
your Pixel Machine model and configuration, the screen may be 1024x1024 or 1280x1024 in high resolution 
mode, 720x480 in NTSC mode and 720x576 in PAL mode. Application developers should remember that 
the screen space starts in the upper left with the +y axis going down. 


Functions in this group are: 
« RAYget screen size(ixiy) 
« RAYput_viewport(left,right,top,bottom) 


RAYget_screen size() 





void RAYget screen size(ix,ty) 
int *ix,*iy; 


ix,iy = pointers to the memory locations that contain the screen's dimen- 
s1ons 





The RAYget_screen size function returns the dimensions of the screen in the x and y directions. The x 
dimension is stored in ix; the y dimension is stored in iy. 


RAYput_viewport() 


void RAYput_viewport(left.right,top,bottom) 

int left,righttop,bottom; 

leftright = initial and final x Pixel Coordinates 
top,bottom = initial and final y Pixel Coordinates 


The RAYput_viewport function defines the coordinates of the current rectangular vewport and loads it into 
the current viewport. 


; WViewports must be defined in accordance with the screen's coordinates. The left and mght coordinates 
NOTE! — range from () to screen width - 1, the top and bottom coordinates range from 0) to screen height -1 
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Example: 


To calculate the coordinates of a viewport of size 401x401 in the screen’s center, do the following: 


od N 

{ : 

int xy; 
' RAYget_screen_siza(&x, Ay): /* assume 1280,1024 */ 

max x = x- 1; \ 
max _y =y- 1; 
left = (max_x - 401) / 2: /* 439 */ 
right = max_x - left: /* 840 °/ 
top = (max _y - 401) / 2; /*31Le/ | 
left = max_y - top; /*72°/ 


RAYput_viewport (left, right, top, bottom); 
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RAYIib provides a wide variety of light sources and surface types. In addition to ambient light, three light 
source types (directional, point, and area) can simulate many lighting situations found in nature. 


The light sources cast realistic shadows based on physical light models. Accurate color rendering is 
achieved through ray tracing methods that account for light and surface characteristics, including tran- 
sparent and reflective surfaces. Texture maps can also be applied to surfaces. 


A description of each type of light source is provided below: 


« Directional: a unidirectional light source used to simulate global lighting effects. The intensity of 
the light reflected from the light source depends only on the orientation of the surface relative to the 
light source. It is independent of the relative position and distance of the surface being illuminated. 


Directional light sources are specified by color and a vector pointing toward the light. 
« Point: an omnidirectional light source that is used to simulate localized lighting effects. The intensity 


of the light reflected from the light source depends on the orientation and relative position of the 
surface being illuminated. Point lights attenuate with distance. 


Point light sources are specified by color, position, and intensity of the light. 
« Area: an area light source simulates diffuse light that radiates from a polygonal area, and is used to 


generate soft shadows in a scene. Samples are taken stochasticly from within the polygonal area. 
Each sample is treated as an independent point light source and behaves as such. 


Area light sources are specified by color, intensity, samples per triangle, number of vertices and list 


of vertices. 


Up to RAY_MAX_LIGHT light sources of each type can be defined. Light sources can be turned on and off 
for a given scene. 


In PIClib, lights can be turned on and off for any object in a scene. In RAYlib, however, only the lights that 
NOTE! are on when RAYtrace is called are used to render the scene. 





The following variables are used to describe the lighting calculations presented below: 


la is the ambient light intensity for the scene (from 
RAYambient Intensity). 

Kr is the object’s reflection coefficient (from the reflectivity element of 
RAYsurface_model). 

Kt is the object’s transmission coefficient (from the transparent com- 


ponent of RAYsurface_model). 

Kd(x) is a component of the object’s diffuse reflection coeffient (from the 
d_* elements of RAYsurface_model). 

Ks is the object’s specular reflection coefficient (from the specularity 
element of RAYsurface_model). 
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Va is the normal vector at a point on the object surface. 

VI is the vector from the light source to the point on the object’s surface 
(derived from the x,y,z or nxny,nz elements of RAYlight_source). 

Lce(x) is a component of the color of the light source (from thes, g b ele- 
ments of RAYlight_source). 


Ve is the vector from the object to the eye point. 
Vr is the reflection vector from the object which is the mirror vector of 
VI about Vn. 


Oe is the object’s specular exponent (from the exp element of 
RAYsurface_modal). 


I is the intensity of the light source (from the intensity element of 
RAYlight_source). 

td is temporarily hardwired to 1.0. 

d is the distance from the light source to the point being shaded. 

d(s) is the distance from a sample of an anea light source to the point 
being shaded 


Xx 1S the red, green, and blue components of light. 


If a ray intersects an object, the following formula is used to determine the x component of the color of that 
ray: 
Color(x) = la * Kd(x) + (Kr * reflect(x)) + (Kt * transmitted(x)) + contribution of each light source 


where, 


reflect(x) is color produced by the reflected ray, if any. 

transmitted(x) is the the color produced by the transmitted ray, if any. The direction 
of the transmitted ray is affected by the relative measurement of the 
permativity of two surfaces (from the refraction_index component of 
RAYsurface_model) 


The colors produced by the reflected and transmitted rays are evaluated as if they were primary rays at the 
point of ray intersection. The same calculations described here are used for the reflected and transmitted 


rays. 


The contribution of each light source is determined as follows; a ray is shot from the point of intersection of 
the current ray and the object, toward cach light source. If this shadow ray strikes an opaque object, the 
light source has no contribution on the current object, because it is in shadow. If the shadow ray does not 
intersect any objects, the contribution of the light source is defined by the formula: 


Contribution(x) = A(d) * Cd(x) + A(d) * Cs(x) 
where, 
Cd(x) is the diffuse component of the light source given by the equation: 


Cd(x) = Kd(x) * Le(x) * (Vane VI 
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Cs(x) is the specular component of the light source given by the equation: 
Cs(x) = Ks *Le(x) * (Ve e Vr)**08e 


-4(d) ts an attenuation function which is dependent on the distance (d) of a given light source from the point 
being shaded. 


The value of 4{(d) for each type of light source is given as: 
for direct light sources: 4(d) = 1.0 
for point light sources: A(d) = // (d + td) 
for area light sources: A(d(s)) = 1 / (d(s) + td) 


If the shadow ray intersects one or more transparent objects, the light’s contribution is computed as 
descnibed above, but attenuated for each object by the formulas: 


Contribution (red) *= Kt *(1.0-0.5 * (Kd(green) + Kd(biue))) 
Contnbution (green) *= Kt* (1.0-0.5 * (Kd(red) + Kd(blue))) 
Contribution (blue) *= Kt * (1.0-0.5 * (Kd(red) + Kd(green))) 





| In these calculations, Kt and Kd(x) are taken from the surface mode! of the object that intersects the sha- 
_NOTE| — dow ray. 





In the case of area light sources, a shadow ray is shot at random points in the area polygon, one shadow ray 
for each sample specified in the light source definition. 


If a primary ray does not intersect any objects, the pixel color is set to the color defined by 
RAYbackground color. If a reflected or transmitted ray fails to intersect any objects, its color components 
are set to the color defined by RAYlight_ ambient. 


If a surface is textured, the diffuse components are taken from the texture rather than the surface model. 
In addition, the transparent and reflectivity components may also be modified by the alpha value of the tex- 
ture map. If a pixel of a texture has an 8 bit alpha value ranging from 0 to 127, it redefines the reflectivity 
component to (alpha / 127). If the textured pixel has an alpha value ranging from 128 to 255, it redefines 
the transparent component to ((alpha - 128) / 127). These components are only temporarily modified for 
the current pixel of the texture. 
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The Shading and Lighting functions available in RAYIib are: 
= RAYambient_intensity(Ival) 
« RAYlight ambient(red.green,blue) 
s RAYput light source(type,index,light) 
s RAYlight switch(type,index ight) 
« RAYput_surface_model(surface) 
« RAYset_surface_model(surface) 
Py RAYput_texture(texture,offx,offy,sizex,sizey) 
= RAYset_texture(texture_id) 
« RAYshade_mode(mode) 


RAYambient_intensity() 





void RAYambient_intensity(Ival) 
float Ival; 


val = —_ intensity of the ambient light for a 3D scene. Should range from 0.0 
to 1.0. 





This function sets the intensity of white ambient light in a scene. Ambient light has no specific direction 
and does not cast a shadow in a scene. The ambient intensity should be between 0.0 and 1.0. 


RAYlight_ambient(Q) 





void RAYlight_ambient(red,green,blue) 
float red,green,blue; 


red.green,blue = light component values for ambient color 





This function sets the color of the ambient light for a 3D scene. RAYlight_ambient defines the color when 
a reflected or transmitted ray does not intersect any objects. RAYbackground color defines the color when 
a primary ray does not intersect any objects. 
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Valid values for the light color components range from 0.0 to 1.0 

: Non-reflecting, non-transparent objects will not be affected by RAYlight ambient as they are with the 
_NOTE| corresponding PIClib function, P{Clight ambient. 

a 


nen) 


RAYbackground color() 





void RAYbackground color(red.green,blue) 
float red.green,blue; 


redgreen,blue = = color values for background color of the current viewport 





RAYbackground_color specifies the rgb color of the background. This is the color that is used if a primary 
ray does not intersect any objects in the scene. The colors are specified using an additive rgb color system 
with color components ranging from 0.0 to 1.0. RAYlight ambient can be used to define the color if a 
reflected or transmitted ray does not intersect any objects. 


| [t is recommended that RAYbackground color be set to the same color as RAYlight_ ambient. 
NOTE! 





RAYput_light_source() 


void RAYput light source(type,indexJight) 
int type,index; 
RAYlight source *tight; 


type =  RAY_UGHT_POINT 
=  RAY_UGHT DIRECT 
= RAY_UGHT_AREA 
index = a user-specified number ranging from 0 to RAY _MAX_UGHT used 
to identify a light source. 
“light = pointer to the RAYlight_source structure 
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RAYput light source selects a light source. The type of light selected can be either point, direct or area. 
Up to RAY_MAX_LIGHT light sources of each type can be defined. 


The index is a user-defined number ranging from 0 to RAY_MAX_ LIGHT - 1 that selects a light from an 


array of light sources of the specified type. Each light source needs to be defined according to the following 
RAYlight_source data structure: 


typedef struct { 


float x, y, 2: 
float nx, ny, n2; 
float fr, g, b; 


float exp, angle; 
float intensity; 
long samples; 
jong vertices; 
float *vertex;: 


} RAYlight_source; 


‘The elements x, y, and z define the position of a point light source. nxny, and nz define a vector from any 
object toward a direct light source. The color of light is defined by the elements 7, g andb. The exp and 
angle elements are currently unused. The intensity of point and area lights used in attenuation calculations 
is defined by intensity. samples defines the number of samples per triangle of area light, and vertices 
defines the number of vertices in the polygon defining an area light source. ‘verter is a pointer to the xy 
and z positions of those vertices. 


For point light sources, the light’s position (x, y, 2), color (7, g 6), and intensity must be defined; for direct 
light sources, the light’s direction vector (nx, ny, nz) and color (r, g b) must be defined; for area light 
sources, the color (7, g b), intensity, number of samples per tangle, number of vertices in the area, and a 
list of vertices must be defined. 


Area light sources with more than 3 vertices are tesselated to multiple tnangular area lights, each of 
NOTE| which counts as | light source. The intensity and samples are specified per tnangie. 





Please keep the following points in mind: 
= The viewing transformation for a scene should be defined before defining area light sources. 
« Once a light source is turned on, it remains on until it is turned off. 
« Only the lights that are on when RAYtrace is called are used to render the scene. 


« There is no default setting for RAYput light source, therefore you need to specify a light source. 
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RAYlight_switch() 





void RAYlight switch (type,index,state) 
int type,index,state; 


type = — RAY_LIGHT POINT 
=  RAY_UGHT_DIRECT 
= RAY _LUIGHT AREA 


= RAY_TYPE_ALL 
index = user-defined number to identify light in other operations 
state = flag indicating on/off state of the light 





RAYlight switch selectively turns light sources on (state = RAY_ON) or off (state = RAY_OFF) . Light 
sources are defined with RAYput light source. 


The type argument specifies the light source type: 

# RAY LIGHT DIRECT 

« RAY LIGHT POINT 

# RAY LIGHT AREA 

« RAY_TYPE ALL 
The index argument is a user-defined number assigned to a light source that exists in a user-defined array 
of light sources. Indices may range from 0 to RAY MAX_LIGHT. The constants RAY TYPE ALL and 


RAY LIGHT ALL can be used to manipulate all light sources simultaneously. The following constants can 
also be used to turn lights on and off: 


= RAY BLACKOUT  - switch all light sources off 
s RAY SUNGLASSES - switch all light sources on 


Only the lights that are on when RAYtrace is called are used to render the scene. 
NOTE 
' 
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RAYput_ surface _model() 





int RAYput_surface_model (model) 
RAYsurface_modei *model: 


*model = pointer to the RAYsurface_model structure 





RAYput_surface_model defines a data structure,RAYsurface_model, 

of surface characteristics and sets the current surface model. The current surface model will remain in 
effect until it is overwritten by either another call to RAYput surface model or a call to 

RAYset surface model. The RAYsurface_model data structure is defined as follows: 


typedef struct { 


float a_red, a_green, a_blue; 
float d_red,d_green, d_ blue; 
float s_red,s_green, s_blue; 
float exp; 

float transparent: 

float. specularity; 

float reflectivity; 

float refraction_index; 


} RAYsurface_model; 


The elements (d_red, d_green, d_blue) define the object’s diffuse color. The object’s degree of specularity is 
defined by specu/anty. The object’s specular exponent is defined by exp. The object’s transparency level is 
defined by transparent and ranges from 0.0 (no transparency) to 1.0 (full transparency). The object’s 
reflectivity is defined by reflectivity and ranges from 0.0 (no reflection) to 1.0 (full reflection). The index of 
refraction is defined by refraction_index. The other components of RAYsurface_ model are only present for 
PIClib compatibility and are ignored by RAYIib. 


If a surface is textured, the diffuse components are taken from the texture as opposed to the surface model. 
In addition, the ransparent and reflectivity components may also be modified by the alpha value of the tex- 
ture map. Ifa pixel of a texture has an 8 bit alpha value ranging from 0 to 127, it redefines the reflectivity 
component to (alpha / 127). If the textured pixel has an alpha value ranging from 128 to 255, it redefines 
the transparent component to ((alpha - 128) / 127). These components are only temporarily modified for 
the current pixel of the texture. 


Each time RAYput_surface_model is called, it allocates memory for the specified surface model and 
returns an integer that can be used to access that model. If an application program needs to reuse a surface 
model, it is most efficient to pass the integer returned by RAYput_ surface model to the 
RAYset_surface_model function described below. Keep in mind that each ume RAYput surface model is 
called, memory is allocated for the new surface model description. No checking is done for duplicate sur- 
face models. 
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RAYset_surface_modei() 





void RAYset_surface_model (mode!) 
int model; 


model = index returned from the RAYput surface model call 


The RAYset_surface_model function is unique to RAYlib. It sets the current surface model to the specified 
model, which should be a value returned by RAYput_ surface model. To reduce memory requirements and 
improve the efficiency of application code, RAYset_surface_model should be called whenever you want to 
reuse a previously defined surface model. 


RAYput_ texture(Q) 





int RAYput_texture(texture,offx,offy,sizex,sizey) 
unsigned long *texture; 
unsigned long offx,offy,sizex,sizey; 


texture = format of the texture 

offx,offy = coordinates of the beginning of a texture residing in extended video 
memory 

sizex,sizey = size of a texture 


RAYput_ texture defines a texture map. A texture can either be resident in extended video memory or ina 
memory array on the host. RAYput texture returns an index identifying a texture that can be passed to 
RAYset_texture to set the current texture. RAYput texture returns RAY ERR TEXTURE if you attempt to 
define more than RAY_MAX TEXTURES. The format of the texture is determined by texture: 


texture = RAY_RESIOENT TEXTURE 


The texture resides in extended video memory. The texture begins at x = off, y = offy, and ts of 
size sizex by sizey. Boih sizex and sizey must be positive and not greater than 256. Both offx and 
offy must be positive and not greater than 255. The sum of offx and sizer and the sum of offy and 
sizey must be positive and not greater than 256. Resident textures may be loaded with 
RAYbroadcast data. Once a texture is loaded, it stays in memory until the machine is powered 
down, another texture is loaded, or a program overwrites the texture. Textures will usually be 
overwritten by coptes to external memory or by antialiasing in PIClib. 
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teure!= RAY RESIDENT TEXTURE 


The texture resides on the host and is considered to be a virtual texture. texture is a pointer to an 
array of sizex by sizey longwords each containing an RGBA value. Each byte of the longword is a 
value from 0 to 255 defining the red, green, blue, or alpha component of the texture. offr and offy 
are unused in this mode. sizer and sizey must be positive and less than or equal to 4096. 


RAYset_texture must be called to use a texture defined with RAYput texture. 


If a surface is textured, the diffuse components are taken from the texture rather than the surface model. 
In addition, the transparent and reflectivity components may also be modified by the alpha value of the tex- 
ture map. If a pixel of a texture has an 8-bit alpha value ranging from 0 to 127, it redefines the reflectivity 
component to (alpha / 127). If the textured pixel has an alpha value ranging from 128 to 255, it redefines 
the transparent component to ((alpha - 128) / 127). These components are only temporarily modified for 
the current pixel of the texture. 





texture = RAY RESIDENT_TEXTURE is not supported on Pixel Machine models 916 and 920 in high reso- 
NOTE: lution mode, however it is supported in NTSC mode on all models. 





RAYset_texture() 





void RAYset_texture(texture_id) 
int texture id; 


texture id = texture index 


RAYset_texture sets the current texture map to the specified texture id; texture_id should be the value 
returned by the RAYput texture call. Any polygons subsequently defined with RAYpoly poiat_uv or 
RAYpoly_point_ov_uv will be textured using the specified texture map. 


The default texture _id is 0, which is the entire 256 x 256 pixel resident texture map. 
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RAYshade_mode() 





void RAYshade_mode(mode) 
int mode: 


mode = = shading mode for ray tracing 





This function selects the shading mode used for ray tracing. The possible values for the mode argument 
are: 


« RAY TRACE 
« RAY SHADOWS 
s RAY NOSHADOWS 
= RAY ANTIALUIAS 
« RAY_NO_ ANTIALIAS 
modes may be combined by adding them together. The default is: 
RAY _TRACE + RAY_ SHADOWS + RAY_NO_ANTIAUAS 





; Each of the default shading modes (RAY_TRACE, RAY SHADOWS and RAY NO ANTIALIAS) are 
NOTE] defined to be 0. A mode only needs to be specified if it is not a default. For example, use 

_ RAYshade mode(RAY NO SHADOWS) instead of RAYshade_mode(RAY TRACE + 
RAY_NO SHADOWS + RAY_NO_ANTIALIAS). 
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To reduce the jagged edges that occur between objects and within textures, you can use antialiasing, which 

takes several stochastic (randomly placed) samples and averages them together to obtain the final value for 
a pixel. RAYIib uses adaptive antialiasing to achieve better quality with a minimum number of samples. In 

many cases, the adaptive nature of the antialiasing technique used allows for a picture quality equivalent to 
100 samples per pixel at only 16 times the rendering speed of a typical unantialiased image. 


Sampling passes are performed sequentially, i.e., the entire unage is rendered for a sampling pass, then 
those pixels that require further sampling are recomputed and their values averaged, and so on. Thus, the 
entire umage is first rendered with no antialiasing, and then it is iteratively improved. Samples are taken 
stochasticly within each pixel. 


The function used to control antialiasing is: 


= RAYsamples(min,max,threshold) 


RAYsamples() 





void RAYsamples(min,max,threshold) 
int min,max; 
float threshold; 


min = the minimum number of passes the ray tracer will make in an 
attempt to antialias the image 


max = the maximum number of passes the ray tracer will make in an 
attempt to antialias the unage 


the minimum contrast needed within a given pixel to require further 
antialiasing 


threshold 





This function establishes the minimum (min) and maximum (mar) oumber of samples taken in any pixel 
during ray tracing to antialias an image. The threshold defines a minimum contrast needed within a pixel to 
require further processing; its value should range between 0.0 and 1.0 


The contrast of a given pixel is computed as: 


Max Luminence in a pixel - Min Luminence 
a ee! 


Max Luminence + Min Luminence 


where luminance ts defined as: 


0.3 * red + 0.59 * green + O11 * blue 
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If RAYshade_mode has RAY_ANTIALIAS set, the minimum oumber of samples is taken at every pixel. 
Further samples are taken only for those pixels that exceed the contrast threshold. The contrast is checked 
after each additional sample. Sampling occurs until each pixel falls within the specified threshold or the 
maximum number of samples is reached. 
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Display Control 


This set of functions performs operations on pixels, images, viewports, and data memory, such as 
reading/ writing scan line operations. The functions are: 


=s RAYclear_viewport() « RAYget_scan line() 

« RAYdouble_buffer(mode) # RAYbroadcast_data() 

= RAYswap_buffer() # RAYcopy_front_to_back() 
s RAYget_buffer_mode() « RAYcopy_back_to_ext() 

= RAYget_buffer() s RAYcopy_ext_to_back() 


# RAYput scan _line() 


RAYclear_ viewport() 


void RAYclear_viewport(r,g,b,a) 
Moat r.g,b,a; 


r.g,b,a = red, green, blue, and alpha indices for the viewport 





RAYclear_viewport clears the current viewport to the specified 7gb color and the overlay piane to the 
specified alpha (a) index. This function is primarily used to clear the entire screen or to display drop sha- 


dows. 





; Because RAYIib will set every pixel in the current vewport when it ray traces, there is no need to clear 
'NOTE| the wewport being ray traced. 


——— 
i 


RAYdouble_buffer() 


void RAYdouble_buffer(mode) 
int mode; 


mode 7 RAY _ON or RAY OFF 
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The RAYdouble_buffer function enables or disables the use of double buffering. When enabled, objects are 
drawn into the back buffer, which is not displayed on the screen. (When in double buffering mode, use the 
RAYswap buffer function after completing a frame.) When disabled, objects are drawn into the front 
buffer only, which is displayed on the screen. The default setting is RAY_OFF. 


RAYswap _buffer() 





void RAYswap_buffer() 





The RAYswap_buffer function swaps the back and front buffers. This function is called during animation. 
Objects are drawn in the back buffer and displayed in the front buffer. (The back buffer is not displayed.) 





| Be sure to enable double buffering before using RAYswap_buffer. 
NOTE 





i 


RAYget_butfer_mode() 





int RAYget_buffer_mode() 





The RAYget_buffer_mode function returns an integer indicating which buffer mode is being used (single or 
double). RAY_SINGLE BUFFER indicates single buffer mode; RAY DOUBLE BUFFER indicates double 
buffer mode. The default setting is RAY SINGLE BUFFER. 


RAYget_bufter( 





int RAYget_buffer() 





The RAYget_buffer function returns an integer indicating the number of the current display buffer. The 
number is either RAY_ BUFFER ZERO or RAY BUFFER ONE. When you initialize RAYtib, the front 
buffer is RAY_ BUFFER ZERO (this buffer is displayed on the screen) and the back buffer is 

RAY BUFFER ONE. 
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Dispiay Control 


void RAYput_scan_line(ix,ly,red,green,blue.alpha,npixl,mode) 


int ix,iy; 


RAY pixel *red, *green, *blue, *alpha; 
int npixi,mode; 


= the coordinates of the scan line. The left-most pixel of the scan line 


ix,iy 
is positioned at Pixel Coordinates (ixiv) (see Figure 3-5). 
red.green,bluelpha == arrays that determine the color of each pixel 
npixi = the number of pixels in the scan line. RAYput_scan_line can write 
an individual pixel by setting npiz to one. 
mode RAY_RGB PIXELS Each pixel is 24 bits of rgb; 8 bits from each red, 


RAY_RGBA_PIXELS 


RAY_RGBA_PACKED PIXELS 


RAY_ABGR_PACKED PIXELS 


RAY_AGB ENCODED PIXELS 


RAY_EXTENDED_VRAM 


RAY COMPOSITE 


green, blue array. 

Each pixel is 32 bits of rgba; 8 bits from each red, 

green, blue, alpha array. 

Each pixel is 32 bits of rgba from a packed array 

pointed to by red. The pixel components are stored 

in rgba order. The first byte in ved contains the red 

component of the first pixel. 

Each pucel is 32-bits of rgba from a packed array 

pointed to by red. The pixel components are stored 

in abgr order. The first byte in red contains the 

alpha component of the first pixel. 

Each pixel is 24 bits of rgb; 8 bits from each red, 

green, blue array. The a/pha array contains count 

numbers that determine how many pixels of the 

same color are to be written. A count number can 

range from 0, indicating that the run is 1 pixel long, 

to 255, indicating that the run is 256 pixels long. In 

this mode, npud refers to the number of runs in the 

scan line. 

If RAY_EXTENDED VRAM is added to mode, the 

scan line is written into the extended video 

memory. 

Combunes current image on screen with input scan 

line according to the formula: 

RGB .. = RGB “a + RGB. *(l-a) 
scm it 


scm 
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The RAYput_scan_line function lets you write a scan line of rgb or rgba pixels to the screen by specifying 
the location of the first (left-most) pixel (ixiy); the number of pixels, npixi; the color of each pixel, red, 
green, blue, alpha, which are arrays of length npix/; and the format of the pixels (mode). 


If the system is in double-buffer mode, the scan line will be written to the write buffer nor the display buffer. 
NOTE 
t 
RAYget scan lined 





int RAYget_scan_line(ix,iy,red.green,blue,alpha,npixl,mode) 


int ix,iy; 

RAYpixel *red, *green, *blue, *alpha; 

int opixls 

int mode; 

ix,iy = the coordinates of the scan line. The left-most pixel of the scan line 
is positioned at Pixel Coordinates (ixiy). (See Figure 3-5). 

red.green,blueilpha = arrays to store the scan line 

opixi = the number of pixels in the scan line. RAYget_scan line can read an 
individual pixel by setting npix/ to one. 

mode = RAY _RGB PIXELS Each pixel is 24 bits of rgb (8 bits stored to each 

’ red, green, blue array). 
=  RAY_RGBA PIXELS Each pixel is 32 bits rgba (8 bits stored to each red, 


green, blue, alpha array) 

=  RAY_RGBA_PACKED PIXELS Each pixel is 32 bits of rgba stored to a packed 
array pointed to by red. The pixel components are 
stored in rgba order. The first byte in red contains 
the red component of the first pixel. 

=  RAY_ABGR_PACKED PIXELS Each pixel is 32 bits of rgba written to an array 
pointed to by red. The pixel components are stored 
in abrg. order. The first byte in red contains the 
alpha component of the first pixel. 
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mode 


W 


RAY_RGB ENCODED PIXELS Each pixel is 24 bits of rgb; 8 bits from each red, 
green, biue array. The a/péa array contains count 
numbers that determine how many pixels of the 
same color were read. A count number can range 
from 0, indicating that the run is 1 pixel long, to 
255, indicating that the run is 256 pixels long. In 
this mode, npix/ refers to the number of runs in the 
scan line. 


RAY_EXTENDED _VRAM If RAY_EXTENDED VRAM is added to mode, the 
scan line is read from the extended video memory. 





The RAYget_scan line function lets you read a scan line of rgb or rgba pixels from the screen by specifying 
the location of the first (left-most) pixel of the scan line, (ix iv); the number of pixels in the scan line, npiri; 
and the format used to read the pixels, mode. 


| If the system is in double-buffer mode, the scan line will be read from the write buffer and nov the 
| NOTE! display buffer. It is recommended that you call RAYwait_psync() before the first call to 
| RAY¢get_scan line. This ensures that the entire frame has been drawn before any scan lines are read. 


RAYbroadcast_ data() 





void RAYbroadcast_data(memory,ix,iy,data,nword) 
int memory, ix, iy; 


int *data; 

int nword; 

int mode; 

memory = RAY BROADCAST _VRAM 

ixiy = the starting x and y memory addresses 

data = an array of 32-bit words 

oword = the aumber of 32-bit words to be broadcast 

mode =  RAY_RGBA_PACKED PIXELS Each pixel is 32 bits of rgba from a packed array 


pointed to by data. The pixel components are 


stored in rpba order. The first byte in data contains 


the red component of the first pixel. 
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mode = RAY_ABGR PACKED PIXELS Each pixel is 32-bits of rgba from a packed array 
pointed to by data. The pixel components are 
stored in abgr order. The first byte in data contains 
the alpha component of the first pixel. 





The RAYbroadcast_data function broadcasts a line of data to extended video memory (smemory = 
RAY BROADCAST _VRAM). The data consists of 32-bit words stored in an array data. 


If the data is broadcast to the extended video memory, each 32-bit word should be organized as four 8-bit 
pixel components. These components can be stored in rgba or in abgr order depending on the parameter 
mode. The aumber of 32-bit words of data to be broadcast is set by nword. The starting x and y memory 
addresses are i,/y. A common use of RAYbroadcast_data is to broadcast textures to VRAM 50 that all 
nodes receive the same data. 


RAYcopy_front_to_back( 





void RAYcopy front_to_back() 





The RAYcopy front_to_back function copies the contents of the current viewport from the front buffer to 
the back buffer. This function is useful when doing double buffered animation. 


RAYcopy back to ext() 





void RAYcopy_ back to ext(buffer,ix,ly) 
int buffer; 

int ix, iy; 

RAY TOP BUFFER 


= RAY_BOTTOM BUFFER 
= RAY _SCREEN BUFFER 


ix, iy = coordinates in an off-screen image buffer. These coordinates are 
used with the RAY_ SCREEN BUFFER constant to specify where in 
the off-screen image buffer to copy the contents of the current 


viewport. 


buffer 
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The RAYcopy_back to ext function copies the contents of the current viewport from the back buffer to an 
extended buffer. There are two available extended buffers: RAY_TOP_BUFFER and 

RAY _BOTTOM_BUFFER. These are used for copying rgb planes to off-screen memory for 3D compositing 
and other purposes. When buffer is set to RAY_SCREEN BUFFER, the extended memory is treated as a 
single large buffer, and you need to specify the location (ix iy) indicating where to place the contents of the 
current viewport. 


The size of the off-screen buffer varies, depending on the model being used. Consult the table below to 
determine the off-screen buffer size for your model. RAY_SCREEN BUFFER should be used to create 
flipbooks or to scroll through large images. 


[ Model | Oft-screen Buffer Size | ff-screen Buffer Size 


oe 










sss 
aoe 2048 
1280x2048 
sae 1280x2048 
932 1024x2048 
932n 1024x2048 
920 - 
920n 1280x1024 
916 : 
9160 1024x1024 


Figure 3-10. 






Since each Pixel Node processor only has access to every other Nx x Ny pixels on the screen, the ixyv values 
have to be chosen carefully when copying to/from RAY_ SCREEN BUFFER. For example, if the current 
viewport starts at a multiple of Nx x Ny pixels on the screen, then the ix iy offset values would also have to 
be a multiple of Nx and Ny. The table below lists the Nx and Ny values for the various Pixel Machine 
models. 





Figure 3-11. 
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x values in multiples of 40 and y values in multiples of 8 will work for all models. 
| NOTE 


as 


RAYcopy_ext_to_back( 





void RAYcopy ext_to_back(buffer,ix,y) 
int buffer; 
int ix, iy; 


buffer 


RAY_TOP_BUFFER 
=  RAY_BOTTOM BUFFER 
= RAY_SCREEN BUFFER 


ix, iy = coordinates in an off-screen image buffer. These coordinates are 
used with the RAY_SCREEN BUFFER constant to specify what part 
of the off-screen image buffer to copy into the current viewport. 





The RAYcopy ext_to_back function copies a region from an extended buffer to the current viewport. Fora 
description of the possible buffer types and use of the uty coordinates, refer to the discussion on 
RAYcopy_back to ext above. 
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The Video functions allow you to manipulate the color lookup tables and query their current status. This 
section discusses the following functions: 


« RAYupdate map(mode) 

a RAYput color_map(red.green,blue) 

= RAYput color_map_entry(index,red.green,blue) 
« RAYput alpha map(red.green,blue) 

= RAYput alpha map entry(index,red.green,blue) 
« RAYget color_map(red.green,blue) 

= RAYget color map entry(index,red.green,blue) 
s RAYget alpha map(red.green,blue) 

s RAYget_ alpha map entry(index,red.green,blue) 





Before altering the color map entries or alpha map entries, RAYupdate map(RAY OFF) should be 


i { 
| = 
|NOTE| called. After the updates are complete, call RAYupdate_map(RAY_ON) to use the new color entries. 


i 


{. 


RAYupdate_map() 





void RAYupdate_map(mode) 
int mode; 


mode = RAY_ON or RAY _OFF 





RAYupdate_map cnables updating of the video lookup tables from the shadow lookup tables when mode = 
RAY _ON. When mode = RAY_OFF, changes to the lookup tables are not displayed until the function is 
re-enabled. Updating of the video lookup tables should be disabled before calling any RAYput color or 


RAYput_ alpha map or map entry commands. 


RAYput_ color mapQ) 





void RAYput color _map(red,green,blue) 
foat *red,*green, *blue; 





RAYlib Functions 3-73 


Video Functions I 


RAYput_color_map loads an entire lookup table, defined by the red, green, and blue arrays, for the rgb 
channel. The red, green and biue arrays are of length RAY_VIDEO TABLE and consist of floating point 
values between 0.0 and 1.0. 


RAYput_color map _ entry( 





int RAYput_color_map _entry(index,red.green,blue) 
int index; 
float red.green,blue; 


index = indicates which entry is being updated 


RAYput_color_map_eatry loads a specified color into the rgb color map. index can range from 0 to 

RAY VIDEO_TABLE - 1. The parameters red, green and blue are floating point values between (1.0 and 1.0. 
RAYput_color_map_ entry returns RAY_ERR_ARG if index is out of range, otherwise RAY ERR OK is 
returned. 


RAYput_alpha_map( 


void RAYput_alpha_map(red,green,blue) 
float *red,*green,*blue; 


RAYput_alpha_map loads an entire lookup table, defined by the red, green, and blue arrays, for the alpha 
channel. The red, green and biue arrays are of length RAY_VIDEO_ TABLE and consist of floating point 
values between 0.0 and 1.0. 


RAYput_alpha_map_entry() 


int RAYput_alpha_map entry(index,red.green,blue) 
int index; 
float red, green, blue; 


index = indicates which entry is being updated 
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RAYput_alpha_map entry loads a specified entry into the color map for the alpha channel. index can 
range from 0 to RAY_VIDEO_TABLE - 1. The parameters red, green, and blue are floating point values 
between 0.0 and 1.0. RAYput_alpha_map entry returns RAY_ERR_ ARG if index is out of range, otherwise 
it returns RAY_ERR_OK. 


RAYget_color map() 





void RAYget_color_map(red.green,blue) 
float *red,*green, *blue; 





RAYget_color_map entry returns a specified rgb entry from the current rgb lookup table. index can range 
from 0 to RAY_VIDEO_TABLE - 1. 


RAYget_color_ map _entry() 





int RAYget_color_map_entry(index,red.green,blue) 
int index; 
float *red,*green,*blue; 





RAYget_color_map entry returns a specified rgb entry from the current rgb lookup table. index can range 
from 0 to RAY_VIOEO_TABLE - 1. RAYget_color_map entry returns RAY_ERR ARG if index is out of 
range, otherwise it returns RAY_ERR_OK. 


RAYget_aipha_mapQ 


void RAYget_alpha_map(red, green, blue) 
Moat *red, *green, *blue; 





RAYget_alpha_map returns arrays containing the current r, g, and b values in the alpha map. Each red, 
green, and biue array is of length RAY VIDEO TABLE. 
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RAYget_ailpha_map_entry() 





int RAYget alpha map entry(index,red.green,blue) 
int index; 
float *red,*green,*biue; 





RAYget_alpha_map entry returns a specified rgb alpha map entry. index can range from 0 to 
RAY_VIDEO TABLE - 1. RAYget_alpba_map entry returns RAY _ERR_ARG if index is out of range, oth- 


erwise it returns RAY_ERR_OK. 
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Definition of Constants 


Constant 





RAY_FALSE 
RAY_TRUE 


RAY_OFF 
RAY_ON 


RAY_ERR_TEXTURE 
RAY_ERR_OK 
RAY_ERR_ ARG 
RAY_ERR_OPEN 
RAY_ERR_NODE 
RAY_ERR FILE 
RAY_ERR LOAD 
RAY_ERR_INVERSE 
RAY_WARN_NO OBJ 
RAY_ERR_INTERNAL 
RAY_HALTED 
RAY_ERR_8AD_BVOL 


RAY_RESIDENT_TEXTURE 
RAY_VIRTUAL_TEXTURE 
RAY MAX TEXTURES 


RAY_MAX_ TRANSFORM 
RAY MAX BASIS 


RAY_QUADRIC_DEFAULT 
RAY PATCH DEFAULT 


RAY BEZIER BASIS 
RAY HERMITE BASIS 
RAY_FOUR_POINT_ BASIS 
RAY B SPLINE BASIS 


RAY _USER_BASIS 0 
RAY_USER BASIS 1 
RAY_USER BASIS 2 
RAY_USER BASIS 3 
RAY_USER BASIS 4 
RAY USER BASIS 5 
Rv USER BASIS 6 
RAY USER BASIS 7 


Value 


0 
(! RAY_FALSE) 


0 
() RAY_OFF) 


QNH = Oo Brno OQOWOONA NMA WHO = 


NOW & WD ~ © 
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Constant Value 


_- Se 


RAY_LIGHT DIRECT 
RAY_LIGHT_POINT 
RAY_ LIGHT SPOT 
RAY LIGHT CONE 
RAY_LIGHT AREA 


Neon — 


RAY_LIGHT_ALL 
RAY TYPE ALL 

RAY_BLACKOUT RAY OFF 
RAY_SUNGLASSES RAY_ON 


RAY_MAX_ LIGHT 16 
RAY VIDEO TABLE 256 


RAY STATISTICS 1 
RAY TIMINGS 
RAY_PAGE STATISTICS 4 
RAY_ALL STATISTICS (RAY_STATISTICS 
+ RAY_TIMINGS 
+ RAY_PAGE_STATISTICS) 


Ls) 


RAY TRACE 

RAY_NO_ SHADOWS 
RAY SHADOWS 
RAY ANTIALIAS 
RAY_NO_ANTIALIAS 


ON O~O 


RAY _LIMIT_REFLECTIONS 1 
RAY_LIMIT_ TRANSPARENCY 2 


RAY MAX TREE DEPTH 16 
RAY_MAX_BVOL_NEST - 100 


RAY_IMAGE PIXELS 2048 


RAY_RGB_PIXELS 
RAY _RGBA PIXELS 

RAY _RGBA_ PACKED PIXELS 

RAY _ABGR_PACKED PIXELS 

RAY RGB_ENCODED PIXELS 

RAY RGB _PACKED_ENCODED PIXELS 
RAY COMPOSITE 


AnNkwn— Oo 


RAY TOP_BUFFER 0x0200 
RAY BOTTOM BUFFER 0x0280 
RAY SCREEN BUFFER 0x0600 
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Constant Value 
RAY _EXT ENDED _VRAM Oxfd 
RAY BROADCAST _VRAM 0 
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Type Definitions 


Because RAYIib and PIClib are compatible in syntax, many of the supporting data structures (typedefs) are 
the same, or as close as possible. In some cases, particular variables may be meaningful for one library but 
meaningless in the other. To maintain compatibility, structures often include names to for both libraries. 
As a result, some variables necessary for one library are ignored by another. 


typedef float RAYmatrix(4](4]; 


typedef struct { 
float X,Y, 2} 
float nx, Ny, NZ; 
float rg, b; 
float exp, angie; 
float intensity; 
long samples, vertices: 
float *vertex; 


} RAYlight_source; 


typedef struct { 
float a_red, a_green, a_blue: 
float d_red, d_green, d_biue; 
float s_red, s_green, s_ blue; 
float exp; 
float transparent; 
float specularity: 
float reflectivity; 
float refraction index; 


} RAYsurtace_modal; 


typedef unsigned char RAYpixel: 
typedef struct { RAYpixel red, green, blue; } RAYrgb_pixel: 
typedef struct { RAYpixel red, green, blue, alpha; } RAYrgba_pixel; 


typedef struct { RAYptxel alpha, blue, green, red; } RAYabgr_pixel; 
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RAYlib Function Return Types 


extern void RAYambient_intensicy(); 
extern void RAYantialias_range(); 
extern void RAYatom(); 

extern void RAYbackground color(); 
extern void RAYbroadcast_data(); 


extern void RAYcamera_view(); 
extern void RAYclear_viewport(); 
extern int RAYclose_bounding volume(); 


extern void RAYcopy_back to_ext(); 
extern void RAYcopy_ext_to_back(); 
extern void RAYcopy_front_to_back(); 
extern void RAYdouble_buffer(); 
extern void RA Yenxit(); 


extern void RA Yext_immediate(); 

extern void RAYget_alpha_map(); 

extern int RAYget_alpha_map entry(); 
extern int RAYget_buffer(); 

extern int RAYget_buffer_mode(); 
extern void RAYget_color_map(); 

extern int RAYget_color_map_entry(); 
extern int RAYget_inverse_transform(); 
extern void RAYget_normal_transform(); 
extern int RAYget_ scan line(); 

extern void RAY¢get_screen size(); 
extern void RAYget_transform(); 

extern void RA Yhalt(); 

extern int RA Yinit(); 


extern void RA Ylight_ambient(); 
extern void RA Ylight_switch(); 


extern void RA Ylookat_view(); 

extern void RA Ylookup_view(); 

extern int RAYopen_bounding volume(); 
extern void RAYpatch geometry _3d(); 
extern int RAYpatch_precision(); 


extern void RAYpersp _project(); 

extern void RAYpolar_view(); 

extern void RAY poly _close(); 

extern void RAYpoly point _3d(); 

extern void RAYpoly_point_nv(); 

extern void RAYpoly_point_nv_uv(); 
extern void RAYpoly_point_uv(); 

extern void RAYpop_transform(); 

extern void RAYpostmultiply_transform(); 


extern void RAYpremultiply transform(); 
extern void RAYpush_transform(); 
extern void RAYput_alpha_map(); 

extern int RAYput_alpha_map entry(); 
extern int RAY put_basis(); 

extern void RAYput_color_map(); 
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aa extern int = RAYput_color_map_entry(); 


extern void = _RAYput_identity transform(); 
extern void RAYput_ light source(); 
extern int RAYput_limit(); | 

exter void” = RAYput_rotate_dx(); 

extern void RAYput_rotate_dy(); 


extern void” RAYput_rotate_dz(); 
extern void) = RAYput_scale’ dx(); 
extern, void. RAYput. scale _dy(); 
extern void’ RAYput scale _dz(); 
extern void” = RAYput_scan line(); 


extern int ” RAY put surface _model(); 
extern int RAYput_texture(); 
extern. void ° RAYput_transform(); 
extern void RAYput_translaie_dx(); 
extern void RAYput_translate_dy(); 
extern void RAYput_translate_dz(); 
extérn void RAYput_viewport(); 
extern int RA Yquadric_precision(); 
extern void RA Yrotate: dx(); 

extern void RA Yrotate_dy(); 

extern void RA Yrotate” dz); 

extern void RA Yrotaté’ vector(); 
extern void RA Yrotate XO; 

extern Void RAYrotate_y();° 

extern void RA Yrotate 2(); 

extern void . RA Ysamples(); - 


extern void RA Yscale();* 
extern void RAYscale_dx(); 
extern void RAYscale_dy(); 
extern void’ RAYscalé_dz();’ 
extern void RAYscale_x(); 
extern void RAYscale_y(); 
extern void’ RAYscale_z(); 


extern int RA Yselect _patch_ basis(); 
extern void RAYset_surface: model(); 
extern void. RAYset _texture(); 


extern void RA Yshade _mode();: 
extern void RA Ysphere();; 

extern void RA Ystatisti¢s(); 
extern void RA Ysuperq’ ellipisoid(); 
extern void RA Ysuperq_byperi(); 
exter void RAYsuperq hyper2(); 
extern void RA Ysuperq torus(); 
extern void RAYswap_buffer(); 
extern int RA Ytrace();_ 

extern void RA Ytranslaté_dx(): 
extern void RA Ytranslate_dy() ; 
extern void RAYtranslite_d2(); 
extern void), RA Ytranslaie _x); 
extérn void RAYtranslate_y(); 
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extern void RAYtranslate_z(); 4 ares 
extern void RAYupdate_map(); 2 hs 
extern void RA Ywindow_project(); axe wie m0 
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